ux-flow-auditor

Name: ux-flow-auditor
Author: heyeddi-com

github.com/heyeddi-comDesign & UI088 installsUpdated 1d ago

About ux-flow-auditor

ux-flow-auditor is a skill for tracing task-oriented user flows and documenting interaction friction. It helps teams verify whether tasks meet click budgets, with flow definitions, reports, and screenshots stored under `.heyeddi/`.

Key features

01Define task flows in JSON
02Trace interactions with Playwright
03Check task click budgets
04Generate reports and screenshots
05Record friction notes under `.heyeddi/`

Use cases

01Measure clicks needed to change settings
02Check task usability after shipping
03Compare desktop and mobile flows
04Verify tasks meet acceptance click budgets

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/heyeddi-com/heyeddi-skills --skill ux-flow-auditor

After installing, type/ux-flow-auditorin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

manifest.json

context/

ANTI_PATTERNS.md

EXAMPLES.md

PROSE_ANTI_SLOP.md

VOCABULARY.md

reference/

cross-pillar-handoff.md

subagents.md

scripts/

_heyeddi_paths.py

_skill_cli.py

init_ux_flows.py

README.md

trace_flow.py

Details

From the project README

UX Flow Auditor

Task-oriented UX: how many clicks to achieve a goal, where users get stuck.

All artifacts go under .heyeddi/docs/ and .heyeddi/audits/: never repo root.

Cross-pillar sync (mandatory)

Read reference/cross-pillar-handoff.md. Bookend every flow trace:

@heyeddi  load_workflow_context --route /path
trace_flow …
update ux-flows report + friction notes
@heyeddi  append_pillar_opinion --pillar ux …
→ @heyeddi-product updates AC if needed; @heyeddi-design notes layout friction

When to use

"How many clicks to update settings?"
Post-ship ease-of-use check
Compare desktop vs mobile flow (separate flow JSON or viewport)
Product acceptance: task completes within click budget

Subagents (default)

See reference/subagents.md. Run trace_flow.py via Task shell (needs dev server + Playwright).

Pipeline

init_ux_flows          → ux-flows.md index + example .flow.json
define steps in ux-flows/<task>.flow.json
trace_flow --task-id   → ux-flows/<task>.md + audit screenshot
agent adds friction notes to report

Instructions

Ensure .heyeddi/product.md defines user tasks (optional context).
python scripts/init_ux_flows.py --project-root <root> once per project.
Add or edit .heyeddi/docs/ux-flows/<task-id>.flow.json with steps (expect, fill, click).
Start dev server; set DEV_SERVER_URL if not http://localhost:5173.
python scripts/trace_flow.py --task-id <id> --project-root <root> --check
Append Friction notes to the generated markdown report.

Flow JSON schema

{
  "task_id": "update-profile",
  "goal": "User saves profile",
  "start_route": "/settings",
  "max_clicks": 4,
  "viewport_width": 1440,
  "steps": [
    { "action": "expect", "selector": ".settings .p-inputtext", "label": "Form visible" },
    { "action": "fill", "selector": ".settings input >> nth=0", "value": "Alex", "label": "Name" },
    { "action": "click", "selector": "button:has-text('Save')", "label": "Save" }
  ]
}

`.heyeddi/` outputs

Path	Purpose
`.heyeddi/docs/ux-flows.md`	Index of tasks, budgets, last run
`.heyeddi/docs/ux-flows/<task>.flow.json`	Machine-readable steps
`.heyeddi/docs/ux-flows/<task>.md`	Human report + friction notes
`.heyeddi/audits/ux-flow/`	Step screenshots

Chain

After @heyeddi-handoff / @heyeddi-design: verify tasks are completable
@visual-auditor: layout proof; this skill: interaction proof
@engineering-excellence: separate concern (code structure)

Comments

Markdown supported