UX Walkthrough

Conduct systematic experience walkthroughs for products, output structured reports and generate local

.docx

files.

Path Convention

<SKILL_ROOT>
= Absolute path of this skill directory.

bash

python3 <SKILL_ROOT>/scripts/<脚本>.py ...

Roles & Standards

Role: Senior B-end Experience Design Expert; Provide actionable suggestions, not subjective complaints
Primary Standard:
```
references/ux-checklist.md
```
(UX Experience Rules)
HiUI Typical Pages:
```
references/hiui-template-baseline.md
```
(Delta Walkthrough; All typical page types in the template library, see the page type index in this document)
Supplementary: Nielsen, WCAG, Brand Specifications; In case of conflicts, prioritize efficiency, comprehension cost, error recovery, and professionalism
Priority: Follow
```
references/severity-rubric.md
```
, do not use preset P-levels from the checklist as substitutes

Delivery Boundaries

The official deliverables of this skill only include: complete Markdown report, structured
```
report.json
```
, annotation verification, and local
```
.docx
```
file
This public skill does not define usage stats, telemetry closeout, network retransmission, or authorization retry after-hook
If upstream workflows require statistics or post-release retransmission, they must be defined and borne by the page generation/publishing skill itself, and cannot be appended to this skill by default
Generating
```
.docx
```
depends on the Python package
```
python-docx
```
; If the environment lacks this package, the task can only report
```
docx_generation
```
failure and cannot claim complete completion

Input → Mode

Input	Mode	Document
Local project directory	`code`	`references/mode.md#code`
`http(s)` URL	`url`	`references/mode.md#url`
Image	`screenshot`	`references/mode.md#screenshot`

When unable to determine, only ask one minimal necessary clarification question.

Three-Stage Main Process

A Pre-check → B Walkthrough & Reporting → C Docx Generation & Self-inspection

Stage A: Pre-check

bash

python3 <SKILL_ROOT>/scripts/precheck_walkthrough.py <输入> --json

Only read
```
next_action
```
,
```
mode
```
,
```
status
```
,
```
gate
```
; In code mode, additionally read
```
runtime_probe
```
```
continue_walkthrough
```
→ Proceed to Phase B; Otherwise, supplement evidence/clarification/failure explanation, do not write a complete report
After code input and gate pass,
```
next_action
```
may be rewritten by runtime probe:
- ```
try_url_walkthrough
```
  → Run URL precheck again on
```
runtime_probe.reachable_urls[0]
```
  , proceed with url mode in Phase B
- ```
start_dev_server_then_url_walkthrough
```
  → First start
```
runtime_probe.suggested_dev_command
```
  ; If successful, run URL precheck; If failed, narrow down code scope
- ```
fallback_code_walkthrough
```
  → Proceed with code mode in Phase B, but must comply with experience boundaries (see
```
mode-code.md
```
  § Experience Boundaries)

Stage B: Walkthrough & Reporting

Code Runtime Priority (Hybrid Walkthrough):

If Phase A returns
```
try_url_walkthrough
```
or local URL is obtained after starting dev server → Switch to url mode: browser screenshot + annotated image,
```
source=url
```
in
```
report.json
```
If dev server fails to start or Phase A returns
```
fallback_code_walkthrough
```
→
```
source=code
```
, note in appendix: "Project not started, conclusions based on code inference"; Only report experience issues that can be confirmed by code

Sequence (Immutable):

HiUI Pre-check (if applicable): Identify page type → Read corresponding section in
```
references/hiui-template-baseline.md
```
(full page types listed in page type index)
Batch-by-Batch Itemized Walkthrough: Follow the order of Batch 1→4 in
```
references/walkthrough-worksheet.md
```
, judge item by item against
```
references/ux-checklist.md
```
; Proceed to the next batch only after completing the worksheet for the current batch
When hitting an item and needing reference, read the anchor pointed to by
```
related_examples
```
of that item (prohibit reading the full text of
```
issue-examples/*.md
```
); For HiUI pages, first check if they are consistent with the baseline compliance default
```
references/ignore-list.md
```
(including §5 HiUI) → Remove false positives
```
references/severity-rubric.md
```
→ Determine P0/P1/P2

Output: Complete Markdown report in the conversation (based on

references/report-template.md

)

Before organizing

report.json

, all 17 items must have

checklist_coverage

filled in (see

report-json.md

pass
must be written as
pass: <verification evidence, >=8 characters>
, bare

pass

is prohibited

Rules for
```
issue
```
/
```
pending:...
```
/
```
n/a:...
```
are in
```
report-json.md
```
Prohibit outputting the "HiUI Template Alignment" module in the deliverable report (HiUI Delta is only used internally during the walkthrough phase; issue descriptions can retain
```
[HiUI-Deviation]
```
/
```
[Business Domain]
```
tags)
Title format:
```
Number. [P-Level] Title
```
URL/Screenshot mode: Confirmed issues must have annotated images and
```
images[].bbox
```
Insufficient evidence → Mark as "Pending Confirmation / Pending Interaction Verification", do not write confirmed issues; If still insufficient, return to Phase A, do not force a complete report

Stage C: Docx Generation & Self-inspection

Annotation (required for screenshot/url mode): Prohibit manual estimation of
```
--box
```
; Must use
```
annotate_issue.py
```
(or
```
locate_in_screenshot.py
```
+
```
preview_bbox.py
```
+
```
annotate.py
```
), output to
```
output/annotations/*-annotated.png
```
(process see
```
annotation-style.md
```
§ Annotation Process)
Organize
```
report.json
```
according to
```
references/report-json.md
```
; In URL/screenshot mode,
```
issues[].images[]
```
must point to annotated versions, set
```
"annotated": true
```
, and record
```
"bbox": [x,y,w,h]
```
Verify checklist coverage gate:

bash

python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json

Verify annotation gate:

bash

python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json

Execute:

bash

python3 <SKILL_ROOT>/scripts/generate_docx.py \
  --report-json <report.json> \
  --output <SKILL_ROOT>/output/<项目名>-ux-report-<YYYYMMDD>.docx \
  --json

Naming, image embedding, and delivery boundaries:
```
references/report-json.md
```
§ DOCX
Screenshot/url mode:
```
generate_docx.py
```
verifies checklist coverage and annotations by default; If not passed, cannot judge as successful completion
Annotated images: Follow
```
references/annotation-style.md
```
(first § Annotation Process, then § Style); Recommended tool:
```
annotate_issue.py
```
Failure → Explain the stuck position and direct cause, cannot claim complete completion

Completion Definition (All Required)

Phase A: Pre-check has passed, or the reason for inability to continue has been clearly stated
Phase B: Complete report (not a summary) has been output in the conversation
Phase C: Docx has been
```
generated
```
in the success path; Failure phase and reason have been explained in the failure path

Analysis completed / Report issued / JSON generated do not equal completion; Docx not generated means incomplete completion.

Phase-Based Document Reading

Phase	Required Reading	On-Demand Reading
A	Corresponding anchor in `mode.md`	`gates.md` § Phase A
B	walkthrough-worksheet, hiui-template-baseline (for HiUI), checklist, ignore-list, severity-rubric	—
C	report-template, report-json, annotation-style	`annotate_issue.py` , `validate_checklist_coverage.py` , `validate_report_annotations.py`

Default Not Required: Underlying script source code and maintenance instructions unrelated to a single walkthrough

Underlying Scripts (Single-Level Debugging Only)

bash

python3 <SKILL_ROOT>/scripts/detect_input_mode.py <输入> --json
python3 <SKILL_ROOT>/scripts/probe_dev_server.py <项目路径> --json
python3 <SKILL_ROOT>/scripts/check_evidence_gate.py --source <mode> ... --json

Pre-Delivery Self-Inspection

Complete report, not a summary
Each issue includes: location, description, improvement suggestions
Title format:
```
Number. [P-Level] Title
```
Itemized inspection completed according to walkthrough-worksheet Batch 1→4
All 17
```
checklist_coverage
```
items filled in, and pass items all contain >=8 characters of verification evidence
```
validate_checklist_coverage.py
```
passed
URL/Screenshot: Each issue has an annotated image, and
```
images[].bbox
```
recorded
```
validate_report_annotations.py
```
passed
Docx generated, or failure reason explained
Absolute path of docx appended at the end (when successful)

Appendix

Gates and Completion Judgment:
```
docs/onboarding/gates.md
```
Checklist:
```
references/ux-checklist.md
```
Batch Worksheet:
```
references/walkthrough-worksheet.md
```
Report Template:
```
references/report-template.md
```
Annotation Specifications:
```
references/annotation-style.md
```

ux-walkthrough

NPX Install

Tags

SKILL.md Content (Chinese)

UX Walkthrough

Path Convention

Roles & Standards

Delivery Boundaries

Input → Mode

Three-Stage Main Process

Stage A: Pre-check

Stage B: Walkthrough & Reporting

Stage C: Docx Generation & Self-inspection

Completion Definition (All Required)

Phase-Based Document Reading

Underlying Scripts (Single-Level Debugging Only)

Pre-Delivery Self-Inspection

Appendix