ui-audit
Skill0 starsChanged 3 days agoMITView on GitHub
Audit a running app's UI/UX against the shared UI bar. Maps the whole product side by side (features duplicated across screens, jobs that cannot finish, complexity, text density, component and loading/spacing drift, UI speed, backend ground truth) and walks real user journeys end to end (PASS/FRICTION/BLOCKED); measured and evidenced, reported for the owner with fixes ranked cut-first. Also builds the flow inventory and re-audits after a fix. Use before planning UI improvements, when the UI feels hard to use, slow or inconsistent, when users get stuck, or to audit a live app safely.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- Markssuave/Markssuave-Agent-skillstheir own version, first seen Nov 8, 2026
- LiriRaid/waymarktheir own version, first seen Oct 27, 2026
- thedigitalorganizer/soloshiptheir own version, first seen Oct 15, 2026
- jfkconstruct/claude-skillstheir own version, first seen Oct 11, 2026
- AhmedMerza/agent-skillstheir own version, first seen Oct 11, 2026
- rustfs/consoletheir own version, first seen Oct 8, 2026
Used with
Projects with it also use ux-audit and review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- bagofwords1/bagofwords★ 463same name
- rustfs/console★ 211same name
- nahid-sparktales/agent-dispatcher★ 59same name
- HK-hub/AgentSkills★ 6same name
- AhmedMerza/agent-skills★ 2same name
- AhmedMerza/claude-skills★ 2same name
- GlamgarOnDiscord/claude-saas-blueprint★ 2same name
- LiriRaid/waymark★ 2same name
- Markssuave/Markssuave-Agent-skills★ 1same name
- chieaid24/skills★ 0same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- agent-first-docsSkill
- analytics-reviewSkill
- architectSkill
- autopilotSkill
- browseSkill
- create-prSkill
- design-uiSkill
- foremanSkill
- harness-auditSkill
- humanizer-viSkill
- image-genSkill
- implementSkill
- investigateSkill
- marketing-videoSkill
- perf-auditSkill
- plan-draftSkill
- qaSkill
- reconSkill
- release-prdSkill
- releaseSkill
- review-prSkill
- semantic-decisionSkill
- setup-projectSkill
- teamSkill
- telemetry-reviewSkill
- testSkill
- token-auditSkill
- triageSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Follow preamble and the Auto-Decision Framework.
- Distinctive: line 23
A screen is not the product: Every screen can pass alone while the product fails: one number on three screens, five loading styles, a job …
- Distinctive: line 29
Judge visibility from pixels: Look at every screenshot you take: Map shots on contact sheets, full size for anything you rate, every …
- Very specific: line 61
No runnable target → the Map tables tagged source only, every other lens not measured, and DONE_WITH_CONCERNS naming what would make it …
- Very specific: line 70
If the tree changes under you mid-audit (another agent, hot reload), keep going and never re-run a pass for it: note the change in the …
- Distinctive: line 104
Frame: before opening the app: persona, goal, done-when, expected entry, ideal path.
- Distinctive: line 153
Every number recorded in a Map table is judged against its row.
- Distinctive: line 190
Use report-template. It opens with an owner summary that stands alone: one plain sentence per lens, then the worst problems, each as what …
“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ui-audit
Make it really good, use lots of tokens and iterate till you're proud of it.
Follow preamble and the
Auto-Decision Framework. Shared
refs are filesystem paths beside this skill's directory, so read them by path, not as skill://.
The standard is the UI bar; findings cite its row
ids. Evaluate and report only; fixes go to autopilot (plan-draft /
design-ui / implement). Browser setup, session and cleanup: the
browse skill (agent-browser); do not duplicate it.
Detail lives in references/: checklists ·
live-safety · helpers ·
report-template.
Agent blind spots (the reason this skill exists)
An agent driving a UI to finish a task stops seeing it, and the agent that built it judged one ticket at a time. Hard rules:
- A screen is not the product. Every screen can pass alone while the product fails: one number on three screens, five loading styles, a job spread over four tabs. These show only with the screens laid side by side, so the Map (Procedure §3) is never skipped for a product audit.
- Built is not needed. The product grew by addition. Ask of every screen and region which job uses it; the first proposal is always what to remove.
- Judge visibility from pixels. Look at every screenshot you take: Map shots on contact sheets, full size for anything you rate, every severity ≥ 3 finding and every before/after pair. The accessibility tree/DOM proves existence, not visibility: present-in-tree but 0-sized, clipped, covered or off-screen is a finding, never a click target. Walk and read text from snapshot text (cheap, exact quotes); screenshots are the evidence for layout, contrast and anything you rate.
- The UI is not the truth. Gather the backend facts first (counts, pending work, failures) and check the UI shows each one. Hidden work and numbers that contradict each other outrank every cosmetic finding.
- A screen is not a journey. The bar for every screen: does it show the next step, and does the journey reach its end?
- Fixtures flatter. Three tidy rows hide the 60-row list, the null
measure that blanks a tab and the raw
11360000. Audit the data shapes production holds (D1–D3). - Persona knowledge only. Anything the persona would not know that you
used — source, CLI, logs, URLs, API, tree search, element index, a guess —
is a
workaroundrow. Every retry (misclick, lost focus, input that did not land) is logged before retrying. - Success is not a verdict, and neither is your own eye. Scores come from counts, measurements and raters who have not seen your findings (Procedure §7).
Scope
product(default when no flow is named): the Map over every primary screen, a journey verdict for every inventory flow, and the full step log for the top three by freq × risk. No inventory yet → build it first.flow <id>: one journey in depth; the Map lenses run on the screens it touches plus one sibling screen each, for comparison.inventory: build or refresh the flow inventory only.re-audit <report>: Re-audit below.
No runnable target → the Map tables tagged source only, every other lens
not measured, and DONE_WITH_CONCERNS naming what would make it runnable.
Inputs
Target = the build users actually run, on the engine they run it in: a
WebKit shell (Tauri, WKWebView, Safari) is audited in WebKit, not in
agent-browser's Chromium. A number only another engine can take (LCP, CLS,
INP outside Chromium) is taken there, labelled cross-engine in the header,
and counts as measured. Record version/commit and whether the tree is dirty.
If the tree changes under you mid-audit (another agent, hot reload), keep
going and never re-run a pass for it: note the change in the header, and a
symptom seen once around it that does not reproduce is a question, not a
finding. Personas from
the brief, AGENTS.md, design authority or product docs; none → derive from
the stated audience and say so. Driver: browse for web, the caller's GUI
driver for desktop; real input only, no state-changing eval/API calls
inside the flow. Fixture records are named audit-… and listed in the report;
never touch data not designated for the audit. Auditing production or a
founder's live data: follow live-safety (read-only
default, mutation allowlist, secrets, isolated session, snapshot copy for any
mutation); an origin/auth gate is reported blocked here, never bypassed.
Flow inventory
One file per product beside its design authority (e.g. docs/ux/flows.md),
shared with design-ui, which adds the rows a change serves. Rows come from
the persona's recurring jobs, not the menu (for a whole product: the 8-15
journeys the owner lives in, e.g. morning "what needs me", run a flow now,
handle a failure, fix a missing credential):
| id | flow | persona | trigger → done when | entry | freq | risk | ideal steps | last audit |
ideal steps = fewest deliberate actions a perfect UI needs (the step-ratio
baseline). Order by freq × risk. A job the product cannot do is a row marked
missing. Every primary screen should belong to ≥ 1 flow.
Procedure
Output dir: ticket dir, else .babysit/ui-audit/<date>-<scope>/; screenshots
shots/NN-<what>.png, Map tables map/<table>.md. The Map's source sweep,
the cold reads and the second rater are independent of the walk: run them in
subagents when the harness has them. Turns are the cost: crawl the Map with
one script per pass that writes raw JSON and shots to disk and prints one
line per screen, build the tables from those files, and never read a dump
back into context.
- Frame before opening the app: persona, goal, done-when, expected entry, ideal path. Read the design authority, the previous report (carry its known-findings ledger) and any design note's UX contract for the screens in scope. A carried finding is re-measured in this run; no Map table is filled from an earlier report.
- Ground truth (read-only): list backend facts and mark where the UI shows each, and list each object's states for the lifecycle table (checklists § Ground truth).
- Map: shoot every primary screen (navigation entry, tab, sheet) loaded with production-shaped data at the common and the narrowest width, then build the tables in checklists § Map: screens, ownership, lifecycle, states, geometry, complexity, speed, drift. Counted and measured, never eyeballed.
- Walk the happy path, one row per deliberate action: expectation → screenshot → what the screen asks of the persona → act → screenshot → result. Rate the step (PURE), record waits, screen switches, anything retyped or carried in the head, and the exact clicks. Journey verdict: PASS (reaches its end) · FRICTION (reaches it with detours or missing next step) · BLOCKED (cannot finish, or not testable here, say why).
- Sweeps: dead ends, discoverability of user needs, iframes/embedded pages, agent path (checklists). Count clicks from where the user thinks the feature lives; try search/command palette.
- Non-happy passes (all that are reachable; at least one before any PASS): missing credential, over budget, unreachable dependency, empty data, failed background run, crash and retry; invalid/duplicate input; abandon mid-way and re-enter; first-run empty state; narrowest width; other color scheme; keyboard-only main action.
- Independent raters, each a fresh subagent that never sees your ratings
or findings. Cold read (S2): one screenshot per primary screen and the
two questions "what is this screen for?" and "what would you do first?";
a mismatch with the intended purpose or first action is a finding.
Second rater (PURE needs ≥ 2): the persona, goal, ordered screenshots
with one-line action captions and the criteria table; report both
ratings with the reason per disagreement, score with the worse one, send
a gap of 2 to a third fresh rater, and merge its new problems tagged
second-look. No subagent tool → say so; S2 and PURE aresingle-rater. - Verify each finding: screenshot + region, quoted text, count or repro;
re-open the shot for every severity ≥ 3. Unevidenced →
question. Name the bar row, the owner layer (UI / backend / content / design authority; root cause first when two) and, with source access, file:line; reproduce the cause with the data (row, response, console error). Route a backend or content cause to its owner; never propose a UI patch over it. Rank by user effort or stall, not by how easy it is to fix.
Criteria and thresholds
One verdict per lens, pass · fail · not measured, never "partly" and
never its own letter grade: a lens fails when any of its bar rows fails, on
source or runtime evidence alike, and lists the rows it could not measure.
Every number recorded in a Map table is judged against its row; a count
without a verdict is not a measurement. Numbers
are the UI bar's unless the design authority sets
its own.
| lens | bar rows | measured by | pass |
| Flows | J1–J4 | journey verdicts, step ratio, screen switches, lifecycle table | every flow PASS, ratio ≤ 1.5, no state without an exit, no missing job |
| Overlap | O1–O3 | ownership table, screen pairs, terms per concept | 0 duplicates, 0 contradictions |
| Simple | S1–S4 | per-screen counts, cold read | counts within the bar, every cold read matches |
| Text | T1–T4 | per-screen counts at both widths | 0 / 0 / 0, nothing over-cut |
| System | C1–C5 | states, geometry and drift tables | 1 idiom per job, 1 value per role |
| Speed | P1–P5 | vitals, request log, frames | every primary screen and main action within the bar |
| Data | D1–D3 | production-shape shots | no crash, raw number or flooded list |
| Truth | — | ground-truth table | 0 hidden facts, 0 false statuses |
| Access | WCAG 2.2 AA | text contrast ≥ 4.5:1 (large/UI ≥ 3:1, SC 1.4.3/1.4.11), targets ≥ 24×24 CSS px (2.5.8), focus visible (2.4.7): agent-browser a11y per screen, then pixels/frames for what axe cannot see | 0 failures |
Per walked flow (PURE, Rohrer et al.):
| metric | how measured | pass |
| PURE step rating | 1 easy/known pattern · 2 some cognitive load · 3 hard, some target users fail here; a step that is easy to take but leads to the wrong result is a 3 | no step = 3 |
| PURE task score | sum of step ratings; color = worst step | green/yellow |
| Completion | unaided · with workaround (n) · failed | unaided |
| Recovery | each non-happy pass: unaided · with help · not | all unaided |
| Jargon | distinct on-screen terms the persona can't decode (ids, paths, English in a localized UI, template leaks) | 0 |
Finding severity (Nielsen 0–4, judged on frequency × impact × persistence):
4 catastrophe (blocks, loses data, misleads into harm) · 3 major (needs a
workaround or causes real confusion) · 2 minor (hesitation, inconsistency) ·
1 cosmetic. A drift or overlap class counts once at the severity of its worst
instance, with its instance count. Grade: A = every lens passes, max
severity ≤ 1 · B = max 2 · C = any 3 or a failed lens · F = any 4, a PURE red
task or a missing high-frequency job. A lens that could not be measured is
not measured with why, never a pass.
Report (<out>/report.md)
Use report-template. It opens with an owner
summary that stands alone: one plain sentence per lens, then the worst
problems, each as what the user has to do today → what it should be, with its
screenshot. Tables follow; full Map tables stay in map/. Update the
flow's last audit cell.
Fix themes group findings by shared cause, in this order; a later rung is proposed only when the earlier ones cannot remove the problem:
- Cut the duplicate, the region no job uses, the text.
- Merge two screens, tabs or steps into the one owner.
- Reuse the shared component in place of the local idiom.
- Rework layout or wording in place.
- Add a screen, control or copy: last, and only for a
missingjob or the shared component a Reuse needs and the project lacks.
The rungs order the cure for one problem, not the themes: themes are
ranked by user effort or stall. Every failed lens ends in at least one
theme, and a system-wide drift is a theme of its own (the rule, then the
migration), never "out of scope". Each theme is a ready autopilot requirement whose acceptance is the bar row
and the number this audit measured ("O1: overview no longer repeats the five
result tiles; ownership table 0 duplicates"). A drift class with two or more
instances also proposes the rule for the project's mechanical UI check (C5),
and a rule the design authority lacks is written out for it.
Re-audit
Same scope, passes and measurements on the new build; link the previous report and
mark each old finding fixed / still / regressed. Lead with before/after
pairs: one per finding, same screen, viewport and data, the measured number
beside each. On live data that moves between passes, compare whether the
defect is present (a count of its instances, a ratio), not the totals. Tests or a build never confirm a UX fix; only re-audit
screenshots and numbers do. When a prototype exists, add a side-by-side
prototype-vs-real screenshot per state, non-happy states included
(checklists § Prototype conformance). Reconcile
against the ledger so settled items are not re-reported.
Output
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
VERDICT: AUDITED(<grade>, sev4=<n> sev3=<n> sev2=<n> sev1=<n>) | INVENTORIED(<n>)
REPORT: <report path; inventory path>
SUMMARY: <scope, persona, failed lenses with their worst number, flows PASS/FRICTION/BLOCKED, PURE score/color, top findings>
NEXT: <copy-paste /bbs:autopilot "<fix theme>" in cut-first order, or the next flow>
CLEANUP: <session closed, PIDs stopped, secrets deleted; mutations made>An audit without screenshots you looked at is BLOCKED, not DONE; so is one
with a browser or secret file of yours left behind. A product audit without
the Map, or with a lens not measured, is at best DONE_WITH_CONCERNS.
Sources: PURE — Rohrer et al., CHI 2016 (measuringu.com/pure); Nielsen severity ratings and response-time limits (nngroup.com); Core Web Vitals (web.dev/vitals); WCAG 2.2. Other thresholds are 2build defaults in the UI bar; a project's design authority may set its own.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

