# UX Persona > Embody a user persona and walk through ONE usage flow of a web application THROUGH THE UI (starting from the flow's entry point, never typing internal URLs), judging whether the journey is usable and recording actionable findings. Takes the flow as an argument. Use when you want to "test as a user", "check if it's usable", "walk flow X as a persona", "validate the usability of a screen/journey", or run a flow with Webwright-style replayable screenshots/log evidence. - Skill: `djalmajr/ux-persona` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add djalmajr/ux-persona` - Raw SKILL.md: https://api.skillmd.com/api/skills/djalmajr/ux-persona/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: djalmajr (https://skillmd.com/u/djalmajr) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/djalmajr/ux-persona --- # ux-persona — persona-driven usability walkthrough You become a **real user** and walk through **one** usage flow of the application, judging whether it is **usable** — not whether the code "works", but whether a real person can reach the goal on their own. You record every point of friction and deliver an actionable report. Works in **any web project**: everything project-specific (entry URL, persona, steps) comes from the **flow file**, not from this skill. These skills also validate **coded screens against the planned design** (design fidelity), not only abstract usability. When a flow (or a step) declares a **design reference** (`design_ref` — e.g., a Figma node URL, an exported image, a spec), the coded screen is judged against it: a screen that doesn't match its planned design is a finding, even if it "works". ## Input (the flow comes FIRST) - `$ARGUMENTS` = path to a **flow file** (convention: `e2e/flows/.md` in the project). If empty, list the available flows in the project and ask which to run. - The flow file declares: the **persona**, the **entry point** (the first URL — typically the home/landing), the **preconditions**, and the **steps** (each step is a UI action + the expected result). - The **persona** is the lens you adopt. Resolve it in this order: 1. A project persona at `e2e/personas/.md` (project-specific). 2. A **common persona bundled with this skill** at `personas/.md` (relative to this SKILL.md) — see *Bundled personas* below. 3. Fallback: a novice user, in a hurry, who does not type URLs or guess paths. ## Golden rule (non-negotiable) **You navigate only through the interface.** Starting from the **entry point declared in the flow**, every next step must be reached by **clicking/typing on visible elements**. **NEVER** type an internal route URL to "jump" to a screen. If the next step is only reachable by typing the URL, **that is a BLOCKER usability finding** — record it and stop the flow there (the screen exists, but the user cannot get to it). Falling back to the direct URL hides the bug; don't. ## Execution backend Default to the browser-automation tools available in the session. Use the Webwright skill/plugin as the execution backend when the user explicitly asks for Webwright, replayable evidence, a generated browser script, or a stronger screenshot/action-log audit trail. When using Webwright: - Keep this skill's flow file as the source of truth. Translate the flow's user goal, steps, preconditions, expected result, persona lens, and any `design_refs` into Webwright critical points. - Preserve the golden rule: the generated script must start at the flow `entry` URL and reach every later screen through visible UI actions, never by typing internal URLs. - Treat Webwright `final_runs/run_/` artifacts as evidence, not as the durable report. Cite the relevant screenshots/log lines in this skill's normal `e2e/usability/--.md` report. - If Webwright succeeds mechanically but the persona rubric finds poor discoverability, unclear copy, missing feedback, design mismatch, or fake data, record that as a usability finding. Automation success is not UX success. - If the Webwright script becomes broadly useful as a regression, recommend porting the stable path into the project's native Playwright E2E suite; do not treat generated Webwright scripts as the CI source of truth. ## Procedure 1. **Preconditions.** Read the flow. Confirm the app is reachable at the flow's **entry point** (if not, start it via the project's run command, or report and stop) and that the flow's minimal data exists. 2. **Open the browser** (the browser-automation tools available in the session): get the tab context → **create a new tab** for this walkthrough → navigate to the **entry point**. Take an initial screenshot. 3. **Embody the persona.** For each step: - **Narrate in the first person, in character** ("As , I want . I look for something like…"). - Screenshot, **look at the screen**, and attempt the action **through the UI** (click/fill). - **Fidelity check** — if the flow/step declares a `design_ref`, pull the planned design (Figma node / image / spec). **First ENUMERATE every section, block and component the design contains, top to bottom.** Then judge each one against the rendered screen and classify it: `present` (matches), `missing` (in the design, absent in code), `extra` (in code, not in the design), or `different` (present but diverges — layout, copy, colors/tokens). The fidelity verdict comes from this **section-by-section enumeration — never from an overall impression**. **Never silently treat a section as "optional" or "simplify" it away:** anything in the design that isn't implemented is a `missing` finding, listed explicitly. "Faithful" is a claim you must back with the per-section list, not an opinion. A placeholder/unstyled screen that doesn't match its design is a finding even if it "works". - **Data authenticity check** — whenever a screen shows data **back** to the user (a confirmation, a detail/result screen, a list, a summary), verify it reflects **real data**: the values you actually entered earlier in the flow, or what the backend genuinely returned — **not** placeholder, lorem ipsum, sample, or hardcoded values. A polished screen wired to mock/stub content (e.g. "Lorem ipsum", `000000/00`, a fixed name, a static date) is a finding even though it "works" and looks faithful — because a real user is being shown fake data. Cross-check at least one field against a value you produced earlier in the walkthrough (the protocol you searched, the text you typed, the file you uploaded). Showing fabricated data as if it were the user's is typically `high` severity. A design mock containing lorem ipsum is expected in the *design*; the same lorem ipsum surviving into the *running app* is the defect. - **Evaluate** with the rubric below and record what hurt. 4. **Conclude.** Write the report (see *Output*) and return a short summary. ## Usability rubric (assess every step) | Dimension | The persona's question | |---|---| | **Discoverability** | Did I find the path without guessing? Was the action/entry visible? | | **Clarity** | Were labels, titles and instructions clear? Did I know what to fill in? | | **Feedback** | Did the system confirm/respond to each action (success, error, loading)? | | **Friction** | Too many steps/fields? Redundant requests? Info I didn't have? | | **Error/Dead-end** | Did it break, error out, or leave me with no next step? | | **Fidelity** | Does the coded screen match its planned design (`design_ref`)? Brand/header, layout, components, copy, colors/tokens. | | **Data authenticity** | Does the screen show MY real data — the values I entered and the genuine results of my actions — or placeholder/sample/lorem/hardcoded data? Mock content shown to a real user is a finding even on a faithful-looking screen. | Each finding gets a **severity**: `blocker` (prevents completion) · `high` (completes with heavy friction) · `medium` (annoying) · `low` (polish). ## Output (durable report) Write to `e2e/usability/--.md` (get the date from the environment; ask/derive — don't invent): ```markdown # Usability — () - **Persona:** · **Date:** · **Entry:** - **Verdict:** ✅ completable | ⚠️ completable with friction | ❌ blocked at "" ## Walkthrough ## Findings (prioritized) | # | Severity | Step | What happened | Suggested fix | |---|---|---|---|---| | 1 | blocker | ... | ... | ... | ## Key screens ``` Return at the end: verdict + number of findings per severity + the report path. ## Bundled personas This skill ships a set of common, project-agnostic personas under `personas/` (next to this file), usable out of the box: `novice`, `rushed`, `skeptical`, `mobile`, `accessibility`, `power-user`. A project can define its own under `e2e/personas/` (which take precedence). See `personas/README.md` for the catalog. ## Operating notes - **Don't fake success:** if the page didn't respond, say "no feedback" — that's a finding, not your failure. - **Anti-loop:** if a browser action fails 2–3 times, stop and report; don't keep re-clicking or wander into screens outside the flow. - Use plausible test data; reuse values produced by an earlier step (e.g., a freshly created reference id). If a precondition is missing, record it as a finding/precondition — don't force it. - The browser is a **single shared resource** — validate **one flow at a time**. The `ux-flows` skill invokes you sequentially.