SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsux-walkthrough

ux-walkthrough

Design & creation

View repository

Updated 10-15 23:47

About this skill

UX Walkthrough

Conduct a systematic experience walkthrough of the product, output a structured report and generate a local .docx。

Path conventions

<SKILL_ROOT> = the absolute path of this skill directory.

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

Roles and standards

  • Role: Senior B-end experience design expert; provide actionable recommendations, not subjective complaints
  • Primary standards:references/ux-checklist.md(UX experience rules)
  • HiUI typical pages:references/hiui-template-baseline.md(Delta walkthrough; for all typical page types in the template library, see the page type index in that document)
  • Auxiliary: Nielsen, WCAG, brand specifications; when conflicts arise, prioritize efficiency, comprehension cost, error recovery, and professional feel
  • Priority: based on references/severity-rubric.md as the standard; do not use checklist preset P levels as a substitute

Delivery boundaries

  • The official completion surface of this skill only includes: complete Markdown report, structured report.json, annotation verification, and local .docx
  • This public skill does not define usage stats, telemetry closeout, network retransmission, or authorized retry after-hook
  • If an upstream workflow requires statistics or publish-state retransmission, it must be defined and undertaken by the page generation / publishing skill itself, and must not be appended to this skill by default
  • Generate .docx depends on the Python package python-docx; if the environment lacks it, this task can only report docx_generation failure, and cannot claim full 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, ask only one minimal necessary clarification question.

Three-stage main process

A 前置检查 → B 走查与报告 → C 生 docx 与完成自检

Stage A: Pre-check

python3 <SKILL_ROOT>/scripts/precheck_walkthrough.py <输入> --json
  • Read-only next_action、mode、status、gate; in code mode additionally read runtime_probe
  • continue_walkthrough → proceed to B; otherwise supplement evidence / clarify / provide failure explanation, and do not write a complete report
  • For code input and after the gate passes,next_action may be rewritten by runtime probing:
    • try_url_walkthrough → for runtime_probe.reachable_urls[0] run URL precheck again, and Stage B proceeds as url
    • start_dev_server_then_url_walkthrough → first start runtime_probe.suggested_dev_command; if successful, URL precheck; if failed, narrow to code
    • fallback_code_walkthrough → Stage B proceeds as code, but must comply with experience boundaries (see mode-code.md § Experience boundaries)

Stage B: Walkthrough and report

Code runtime prioritized (hybrid walkthrough):

  1. If A returns try_url_walkthrough or after starting dev a local URL is obtained → switch to url mode: browser screenshots + annotated images,report.json of source=url
  2. If dev startup fails or A returns fallback_code_walkthrough → source=code, the appendix notes "project not started, conclusions based on code inference"; only strongly report experience issues determinable from code

Order (immutable):

  1. HiUI pre-check (if applicable): identify page type → read references/hiui-template-baseline.md corresponding section (the page type index lists all page types)
  2. Batch-by-batch item-by-item walkthrough: follow references/walkthrough-worksheet.md Batch 1→4 order,item by itemagainst references/ux-checklist.md to judge; complete the worksheet for each batch before proceeding to the next
  3. When an item is hit and reference is needed, read that item's related_examples Anchor point pointed to (do not read through issue-examples/*.md the full text); for HiUI pages, first ask whether it is consistent with the baseline compliance default
  4. references/ignore-list.md(including §5 HiUI) → remove false positives
  5. references/severity-rubric.md → determine P0/P1/P2

Output: complete Markdown report in the conversation (references/report-template.md）

Before organizing report.json , you must, for all 17 items , fill in checklist_coverage(see report-json.md）：

  • pass must write pass: <验证证据，>=8 字>, bare pass

  • issue / pending:... / n/a:... rules see report-json.md

  • It is forbidden to output the "HiUI template alignment" module in the delivery report (HiUI Delta is used only internally during the walkthrough phase; the issue description may retain the [HiUI-偏离] / [业务域] tag)

  • Title format:序号. [P级]标题

  • URL/screenshot mode: a confirmed issue must have an annotated image and images[].bbox

  • Insufficient evidence → mark "to be confirmed / pending interaction verification", do not write a confirmed issue; if still insufficient, return to phase A, do not force-write a complete report

Phase C: generate docx and complete self-check

  1. Annotation (required for screenshot / url): manual estimation of --boxis forbidden; you 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)
  2. Organize references/report-json.md according to report.json; for URL/screenshot mode, the issues[].images[] must point to the annotated version, set "annotated": true, and record "bbox": [x,y,w,h]
  3. Validation checklist coverage gate:
python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json
  1. Validate annotation gate:
python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json
  1. Execution:
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：generate_docx.py Default validation checklist coverage and annotation; if not passed, must not determine success completion
  • Annotated image:references/annotation-style.md(first § annotation process, then § style); recommended tools:annotate_issue.py
  • Failure → explain where it got stuck and the direct cause, do not claim it has been fully completed

Definition of done (all required)

  1. A: precheck has passed, or the reason why it cannot continue has been clearly explained
  2. B: a complete report (not a summary) has been output in the conversation
  3. C: on the success path, docx has been generated; on the failure path, the failure phase and reason have been explained

Analyzed / report produced / json generated do not equal completion; if docx is not generated, it does not count as fully complete.

Read documents in phases

Phase Required reading As needed
A mode.md corresponding anchor point 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

Not read by default: underlying script source code and maintenance notes unrelated to a single walkthrough

Underlying scripts (single-layer debugging only)

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-check

  • The report is complete, not a summary
  • Each issue has: location, description, improvement suggestions
  • Title:序号. [P级]标题
  • Checked item by item according to walkthrough-worksheet Batch 1→4
  • checklist_coverage All 17 items have been filled in, and each pass contains >=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 has been generated, or the reason for failure has been explained
  • Absolute path of docx appended at the end (on success)

Appendix

  • Access control and completion determination:docs/onboarding/gates.md
  • Checklist:references/ux-checklist.md
  • Batch worksheet:references/walkthrough-worksheet.md
  • Report template:references/report-template.md
  • Annotation specification:references/annotation-style.md