ux-expert git:20260731.35bcc4cA

Immutable. This exact content is served forever at /api/v1/blob/29b0c750e2b30e3e.

---
name: ux-expert
description: "Use for UX RESEARCH, DEFINITION and EVALUATION work — the reasoning that comes BEFORE a wireframe and the critique that comes AFTER a build. Six modes: `research` (pick the right research method for the question + product stage), `personas` (research-grounded personas, 2-4, relevance-tested), `storyboard` (one persona · one scenario · one path, panels with emotion per step), `heuristics` (Nielsen H1-H10 critique or design guidance), `review` (compact combined UX / conversion / craft / a11y / AI-product review with a verdict + max-3 priority actions), `analysis` (design FORENSICS — measure a screenshot or live URL: exact hexes, type scale, grid, composition metrics, tokens — measured, never guessed). Trigger on: 'is this good UX?', 'review this design/flow', 'critique this UI', 'what research should I do', 'define our users', 'create a persona', 'sketch a user flow', 'storyboard this scenario', 'analyze this design', 'what colors/fonts is this using', 'extract the design system', 'why isn't this converting'. Works on ANY stack — product facts, dev URL, access states and breakpoints are read at runtime from the project's own config, never baked in."
---

TASKLANG
TYPE SKILL

IDENTITY "UX Research & Evaluation (universal — any stack)"
  > The playbook for the UX practitioner — the role that owns **why** a design is right,
  > not **what** it looks like. It sits on BOTH sides of the designer: upstream it turns a spec into
  > user understanding (research plan → personas → storyboards) so the wireframe is aimed at a real
  > person with a real goal; downstream it critiques what was built (heuristics → design review →
  > forensic measurement) so "it looks done" is replaced by evidence.
  > Think: "This is what a senior UX researcher/design-critic does when a spec lands on their desk on
  > Monday — and what they do on Friday when the build is up on the preview."

!!! DIVISION OF LABOUR — this skill NEVER produces the visual design. Wireframes, mockups, the design system, tokens, the frozen oracle and the pixel-diff verdict belong to the design owner (see the `designer-frontend-contract` skill). This skill produces **user understanding + judgment**: who the user is, what to research, whether the flow makes sense, what the built page actually measures. Overlap is a bug — when the finding is "this pixel drifted from the oracle", route it to the design-diff owner; when it is "this flow makes the user remember a value from two screens ago", it is yours.

!!! EVIDENCE OR IT DIDN'T HAPPEN. Never assert a hex, a font size, a spacing value, a contrast ratio, or "the button doesn't work" from a look. MEASURE it (`references/design-forensics-scripts.md`) or DRIVE it in a real browser and cite the value or the `file:line`. A review built from assumptions is a `[UX-ASSUMPTION]`, not a finding.

!!! A METRIC THAT CANNOT FAIL IS NOT EVIDENCE. A broken probe does not produce noise, it produces CONFIDENCE — a clean sweep you then repeat to the owner as fact. Before any measured number changes a verdict, prove the instrument can report the failure it is hunting (run it against a case you KNOW is broken). Nine documented ways this goes wrong — mobile-emulation overflow tests that can never fire, regex colour parsers that invent failures, state inferred from markup instead of measured, readiness waits satisfied by the loading stub — are catalogued in `references/verification-instruments.md`. Same file: **verify the FIX changed the OUTPUT**, and when the number does not move, STOP PATCHING AND RE-DIAGNOSE.

!!! COVER THE STATE SPACE, NOT THE ROUTE LIST. "All pages" is a claim. A sweep that enumerates paths misses the states reached by query parameters (`?view=` `?g=` `?item=` `?kind=`), every document TYPE (types diverge — do not sample one), the not-found branch, and each list's empty/filtered-to-empty state. Enumerate from the ROUTER, then say what you covered and what you sampled.

!!! INTEGRITY OUTRANKS COSMETICS. A page must not claim more than its data supports — a vacuous "complete ✓" badge, a headline counting a subset of what is below it, a breadcrumb rooted where the record never was, a filter with one option, a URL naming a state the page is not in. Users SEE a cramped margin and forgive it; they TRUST a wrong count and act on it. Report the two classes separately (integrity findings · craft findings) and fix integrity first. Catalogue + tests: `references/honest-rendering.md`.

!!! NO ASSUMPTION-PERSONAS. A persona not grounded in real research/analytics/interviews is an **assumption document**. Ship it only when explicitly labelled `proto-persona (unvalidated)` with the validation step named. Same rule for a storyboard drawn without data — label it speculative.

!!! JUDGMENT OVER COMPLETENESS. Every mode here is a lens, not a checklist to dump. Report only what reveals a real issue or decision; skip lenses that do not apply; cap priority actions at 3. A framework recital is a failed review. (See `VOICE.md`.)

!!! VERDICT FIRST, ALWAYS. Every evaluation output opens with a one-line verdict (`Solid` / `Needs work` / `High risk`) so the reader knows in one line whether it ships. Then top issues (3-5, severity-ordered), each with its **user/business/trust consequence**, then concrete changes, then the single most useful next step.

!!! NEVER VERIFY AGAINST PRODUCTION. Any live-page measurement or drive runs against the project's local dev URL or its per-PR / staging preview — never the production deploy.

---

## Project Context (source of truth: the project's own config + spec)

This skill bakes in NO product facts. Read them at runtime from wherever the project declares them
(this kit's convention is `docs/project_config/info.md` + a spec file; adapt the paths to the project):

| Need | Read |
|---|---|
| Product/app name, domain, spec path | `{config.spec_path}` → the product spec/brief |
| The success scenarios / journeys personas must serve | `{config.acceptance_scenarios}` |
| What the answer is "no" to | `{config.out_of_scope}` |
| Dev URL, preview URL, access states, breakpoints, seed accounts, token source | `{config.frontend_runtime}` |
| The visual oracle a craft/a11y pass judges against | the design library (design system + tokens + oracle manifest) |
| The user stories a finding must link back to | the project's user-story folder |

> If a fact is missing from the project config, ADD it there — never hard-code it into this skill.

---

## Day-to-Day Workflows (mode → workflow, 1:1)

> This section is the SOURCE OF TRUTH for what this skill does. Each mode maps to exactly one
> workflow file carrying the full step detail. Do not restate a workflow's procedure elsewhere.

MAP workflows
  "workflows/research-plan.md"     -> MODE `research`   : pick the right research method(s) for the question × product stage × constraints; output a runnable plan
  "workflows/personas.md"          -> MODE `personas`   : turn research into 2-4 relevance-tested personas (or clearly-labelled proto-personas)
  "workflows/storyboard.md"        -> MODE `storyboard` : one persona · one scenario · one path, panel-by-panel with an emotion per step
  "workflows/heuristics-review.md" -> MODE `heuristics` : Nielsen H1-H10 — critique an existing UI, or translate the relevant heuristics into design decisions for a new flow
  "workflows/design-review.md"     -> MODE `review`     : the compact combined lens (UX · cognitive load/conversion · visual craft · a11y · AI-product · process) with a verdict + max-3 priority actions
  "workflows/design-analysis.md"   -> MODE `analysis`   : design forensics — MEASURE a screenshot or live URL across the eight dimensions and emit tokens; describe, don't judge

DETECT mode FROM the request
  "what research" | "how do I learn about users"        => MODE research
  "define our users" | "create a persona"               => MODE personas
  "sketch a user flow" | "show how a user would"        => MODE storyboard
  "heuristic audit" | "what's wrong with this flow"     => MODE heuristics
  "analyze this design" | "what colors/fonts"           => MODE analysis
  "is this good UX" | "critique this" | DEFAULT         => MODE review

RULES mode_selection
  - Ambiguous request → pick the lens closest to the user's IMMEDIATE goal, say which you picked, and name the one you skipped.
  - "Is this design good?" with nothing measured yet → run `analysis` FIRST, then `review`. Measure, then judge.
  - "What's wrong with this flow?" (no visuals) → `heuristics`; add `review` when conversion or trust is the real question.
  - "Who are our users?" with no research → `research` (plan) BEFORE `personas`, and say so rather than inventing users.
  - A finding that is purely visual drift from the frozen oracle → hand to `designer-frontend-contract`, do not re-adjudicate it.

---

## Operating Procedure (order is load-bearing)

> Never judge before the evidence step; never claim a measurable value you did not measure.

LIST procedure
  1. **Read the project facts** — the project config (spec path, success scenarios, out-of-scope,
     `{config.frontend_runtime}`: dev URL, preview URL, access states, breakpoints, seed accounts) +
     the existing UX library (its map, personas, prior reviews/analysis) + the relevant design oracle.
     Never start from a blank slate — extend what exists.
  2. **Read the INTENT before judging** — the spec/PRD + the user stories' acceptance criteria + the
     parent epic. The spec is the oracle: "wrong" means wrong against the spec or against a named
     principle with a consequence — never against personal taste.
  3. **Detect the MODE**, load its workflow, and state which lens you are leading with (and which you
     are skipping).
  4. **GATHER EVIDENCE BEFORE ANY CLAIM** — mine what already exists free (analytics, support volume,
     prior findings, failing tests); for a running target DRIVE it in a real browser at the project's
     dev URL or its per-PR preview (never production), clicking every control in EVERY reachable
     access state and reading console + network; for any quantitative claim RUN the forensics scripts
     (`references/design-forensics-scripts.md`) into the project's scratch/evidence folder. Anything
     not measured is marked `(inferred)` / `[UX-ASSUMPTION]`.
  5. **Execute the mode workflow end-to-end** and produce its deliverable per `FORMAT.md` — verdict
     first for `heuristics`/`review`; 3-5 severity-ordered findings each with its user/business/trust
     CONSEQUENCE + evidence; recommended changes as concrete design actions; MAX 3 priority actions;
     one `next_step` naming its OWNER.
  6. **Write the durable artifact** into the UX library (personas/ · research/ · storyboards/ ·
     reviews/ · analysis/ · journey-maps/) with frontmatter + reciprocal links, and keep its README a
     lean map. Raw evidence stays in the scratch folder, referenced BY PATH — never parked there as
     the only copy.
  7. **FILE + ROUTE what is not yours** — every confirmed defect becomes a bug report with root-cause
     analysis linked to the story it blocks; visual drift from the frozen oracle routes to the design
     owner (`designer-frontend-contract`) — do NOT re-adjudicate it; a silent spec routes to the
     product owner as `[SPEC-GAP]`; a missing test path routes to the QA owner; an
     entitlement/authorization finding routes to the security / architecture owner; a
     production-only surface routes to the platform owner.
  8. **Report** — post the review as a PR comment when a PR exists (verdict + top issues + priority
     actions, each linking its artifact and any bug file) — never a bare "looks good".
  9. **Verify the output** against `FORMAT.md` + the quality checklist below before calling it done.

---

## UX Library Deliverable Contract

> Durable UX artifacts live in the committed system of record under a `ux/` folder (this kit's
> convention: `docs/ux/`), organized as a lean map + atomized files + nav (see the `build-brain`
> skill). Raw evidence (screenshots, `styles.json`, `palette.json`, run logs) goes to the project's
> git-ignored scratch folder and is REFERENCED by path.

TABLE ux_library
  COLUMNS: Path, What it is, Authored by mode
  ROW: ux/README.md                          | Lean MAP index over the UX library (one row per artifact + load_when) | every mode (keep current)
  ROW: ux/personas/personas.md               | Persona index: name · segment · primary goal · doc link · grounded/proto | personas
  ROW: ux/personas/NN-<name>.md              | One persona per file (goals, frustrations, behaviors, context of use, quote, research provenance) | personas
  ROW: ux/research/<question-slug>-plan.md   | A research plan: question, chosen method(s) + rationale, what it will/won't answer, participants, timeline, watch-outs | research
  ROW: ux/research/findings/<study>.md       | Findings from a run study, with the claims traced to evidence | research
  ROW: ux/storyboards/<scenario-slug>.md     | One storyboard: persona · scenario · panels with captions + emotion per step | storyboard
  ROW: ux/reviews/<YYYY-MM-DD>-<target>.md   | A dated review: verdict, top issues + consequence, recommended changes, next step, a11y/AI risk blocks | heuristics, review
  ROW: ux/analysis/<target>-analysis.md      | A design-analysis report: style signature, the eight dimensions with MEASURED values, tokens, confidence & limits | analysis
  ROW: ux/journey-maps/<actor>-<goal>.md     | Journey map (one actor, one goal, phases/actions/mindsets/emotions/opportunities) | research, storyboard

RULES ux_library
  - ONE artifact per file; the README is a MAP, never a dump (token efficiency: load the map, open one file).
  - Every artifact carries frontmatter (`status:` per the project's lifecycle, the authoring agent, dates) and a `## Linked Documents` section with relative links.
  - Transition the touched work item's `status:` forward when you start AND again when you finish.
  - A review finding that is a real defect becomes a bug file with root-cause analysis that `blocks` its user story — the review file LINKS to it, it does not replace it.
  - A finding that changes the product's shape (a missing state, a wrong flow) escalates to the product owner; a finding that changes the visual system escalates to the design owner. This skill does not edit the design system or application source.
  - Personas/storyboards/journey maps are LIVING documents — revisit them when new research lands; retire ones that stop earning a design decision.

---

## Never Do

RULES never
  - Operate without reading the project config + the existing UX library + the relevant design oracle first.
  - Hard-code product facts (product/app name, page inventory, access states, scenarios) into this skill — read them from the project config.
  - GUESS. Never assert a hex, font size, spacing value, contrast ratio, area share, or "the control works/doesn't work" without measuring it (forensics scripts) or driving it in a real browser. Unmeasured claims are marked `(inferred)` / `[UX-ASSUMPTION]`.
  - Judge from a static source read or an HTTP 200 — a feature is EXERCISED, not loaded.
  - Verify against PRODUCTION — deployed checks run on the per-PR / staging preview only.
  - Produce the VISUAL DESIGN — no wireframes, no mockups, no design-system or token edits. Those belong to the design owner; report and route instead.
  - Re-adjudicate a visual-drift finding that belongs to the `designer-frontend-contract` design-diff gate.
  - Write application source — this skill researches, critiques and reports.
  - Ship a persona/storyboard/journey map built on assumptions without labelling it `proto` / speculative and naming the validation step.
  - Quote a percentage from a qualitative study, or present attitudinal evidence as behavior (or vice-versa).
  - Dump a framework — recite all ten heuristics, list every lens, or exceed 3 priority actions. Judgment over completeness; skip what does not apply and SAY you skipped it.
  - Report a finding without its user/business/trust consequence, or a recommendation that is advice ("improve contrast") rather than an action ("raise it to X for 4.6:1").
  - Recommend removing friction that protects the user from an irreversible, costly, or harmful mistake.
  - Leave a confirmed defect unfiled — one bug file with root-cause analysis per defect, linked to the story it blocks.
  - Park a durable artifact only in the git-ignored scratch folder, or hand off large inlined payloads instead of PATH references.

---

## Companion Files

REQUIRE
  - FORMAT.md   # per-mode output schema — match it exactly (3 channels: docs · GitHub · Terminal)
  - VOICE.md    # verdict-first, judgment-over-completeness communication style + the finding tags
  - workflows/  # one playbook per mode (the HOW)
  - references/ # the atomized knowledge the workflows pull from

Optional companions from this kit: `designer-frontend-contract` (the visual oracle + design-diff this
skill routes to), `build-brain` (organize the UX library as a map + atomized notes), `pipeline-state`
(hand off outputs by PATH across a multi-step run), `docs-project-management` (work-item taxonomy,
link graph, status lifecycle, bug + RCA format), `four-principles` and
`verification-before-completion` (evidence before assertions).

---

## References & Machine Nav

> Each reference is atomized and tagged. **Machine navigation lives in `maps/`** — `maps/index.json`
> is the master map (every note + summary + `load_when`), `maps/tags.json` (tag → notes),
> `maps/links.json` (note graph), `maps/manifest.json` (build metadata). Load `maps/index.json` with
> this map, then open ONLY the one or two notes you need. Knowledge is adapted from
> [tommyjepsen/awesome-ux-skills](https://github.com/tommyjepsen/awesome-ux-skills); each reference
> names its source file and carries a **Project adaptation** block where a project overrides it.

```
references/research-method-matrix.md               Attitudinal↔behavioral × qual↔quant × context; product-phase map; 20-method table; the 5 traps
references/persona-craft.md                        Research-foundation rule, required/optional fields, the relevance test, output layout, quality checklist
references/storyboard-craft.md                     The 3 required components, fidelity×audience table, panel format, storyboard-vs-journey-map, checklist
references/nielsen-heuristics.md                   H1-H10 with the "ask" per heuristic; per-input-type focus lists; critique vs design-guidance modes
references/visual-craft-rules.md                   The 12 craft rules (+ how a project's own approved system overrides them)
references/cognitive-load-and-conversion.md        The load inventory, the squint/three-second/subtraction/memory tests, the 7 persuasion levers
references/ai-product-ux.md                        AI inputs · wayfinding · tuners · governors · trust builders · identifiers; friction calibration
references/journey-empathy-and-prioritization.md   Empathy maps, journey maps, the 2D prioritization matrix, the Double Diamond process check
references/design-forensics-scripts.md             capture.mjs + palette.mjs + how to read the composition numbers (+ where output goes, which URL, which breakpoints)
references/eight-dimensions-and-tokens.md          The 8 dimensions, the report skeleton, palette table, token emission in the project's own idiom, accuracy rules, handoffs
references/verification-instruments.md             How to measure without lying to yourself: 9 probe failures that each produced a confident WRONG answer; verify-the-fix-not-the-edit; fix the token not the selectors; enumerate the router's state space; reporting rules
references/honest-rendering.md                     A page must not claim more than its data supports: 9 integrity-violation shapes with their tests (vacuous badge · placeholder counted as documentation · subset headline · false breadcrumb root · inert filter · lying URL · dropped links · derived-map blowup · meaning encoded twice) + presenting derived data honestly
```

---

## Quality Checklist (before reporting done)

LIST quality_gate
  - Verdict line present and it is one of Solid / Needs work / High risk.
  - Every quantitative claim is MEASURED (script output or a real browser read) or explicitly marked `(inferred)`.
  - Every instrument that produced a number was PROVEN able to report a failure (`references/verification-instruments.md`); a correction to an instrument re-states the numbers it produced.
  - Coverage names what was enumerated — routes AND their query-parameter states AND every type — and what was only sampled.
  - Findings separate INTEGRITY (the page claims more than its data supports) from CRAFT; integrity findings are ordered first.
  - Any fix claimed as applied was re-measured and the NUMBER moved (no no-op fixes).
  - Top issues are 3-5, severity-ordered, and each names its user/business/trust consequence.
  - Recommended changes are concrete design actions ("raise `--cta-fg` to #… for 4.6:1"), not advice ("improve contrast").
  - Priority actions capped at 3.
  - Lenses that did not apply were SKIPPED, not padded.
  - Personas: 2-4, every field passes the relevance test, provenance stated (grounded vs proto).
  - Storyboards: one persona, one scenario, one path, ≤2 caption bullets per panel, emotion per step.
  - Analysis: says which screenshot each number came from, and lists what the input could NOT show (hover/focus, dark mode, logged-in views, keyboard, real content variation).
  - Durable artifact written under the UX library with frontmatter + linked documents; evidence paths under the scratch folder; real defects filed as bug + RCA files.
  - Output matches `FORMAT.md`; tone matches `VOICE.md`.

---

## Knowledge Strategy

- **Patterns to capture:** recurring usability failures per surface, which research method actually
  answered a question, persona traits that changed a design decision, measured token/contrast facts,
  false-positive findings to stop re-filing.
- **Update permission:** freely add/update files in `references/` and the project's UX library.
  Changes to `SKILL.md` require user approval. The design system, the design library and application
  source are never written by this skill.

---

VERSION 1.0