agentleFS
hiteshbandhuhiteshbandhu/skills-i-use/skills/ui-ux/SKILL.md

ui-ux

Skill1 starsChanged 5 months agoMITView on GitHub

UI/UX and product review for web interfaces — opinionated principles, checklist-driven audits, polish passes on screenshots, and pre-ship UI gates. Uses Playwright to navigate, screenshot, and smoke-test interactions when a URL is available. Triggers on "review my UI", "polish this", "UX audit", "fix the hero", "make it look professional", "ui pass", "design review", attaches screenshot with UI feedback. Use when building or reviewing interfaces and product flows, not generic code review.

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use deploy.

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.
  • VercelSkill

    deploy

    Deploy applications to Vercel. Use when the user says "deploy", "deploy to Vercel", "push to production", "deploy my app", or "go live".

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the target file(s) or explore the route

    line 47
  2. Distinctive:

    If screenshot provided — treat it as source of truth for what's wrong visually

    line 49
  3. Distinctive:

    Read playwright.md. Always run when a URL is reachable (unless review-only on code with no running app).

    line 55
  4. Distinctive:

    Use Playwright MCP when available.

    line 58
  5. Distinctive:

    If Playwright cannot run, note why in the report and rely on code review + user screenshots — do not skip silently.

    line 65
  6. Distinctive:

    Run review-checklist.md against scope and Playwright results.

    line 72
  7. Distinctive:

    Do not suggest gradients, glow, purple accents, or animation unless user asked.

    line 85
  8. Distinctive:

    When building or polishing:

    line 91
  9. Distinctive:

    After edits, state what changed in plain language

    line 95
  10. Distinctive:

    Re-run Playwright (Step 1b): after implementing — capture after screenshots and confirm failed interaction checks now pass.

    line 99
  11. Very specific:

    When the audit produced Playwright screenshots (most audit/polish passes do), also emit an HTML version from report-template.html — it …

    line 112
  12. Very specific:

    Use the .grid2 before/after pattern for any fix you re-screenshotted.

    line 120
  13. Very specific:

    Keep both in sync — the HTML is the shareable artifact, the .md is the record.

    line 123
  14. Very specific:

    Update {output_dir}/index.md (link both formats):

    line 125

“Common” is measured: kept by at least 6 in 10 of the 7 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

UI/UX — Product-Aware Interface Review

Opinionated UI/UX + product review for web apps. Thinks about jobs-to-be-done before pixels. Works with any coding agent.

Supporting files:

  • principles.md — product + UI/UX rules (read every time)
  • review-checklist.md — structured audit
  • playwright.md — browser verification with Playwright
  • report-template.md — saved review output (the record)
  • report-template.html — shareable HTML report with embedded screenshots

Output: {SKILL_OUTPUT_DIR}/ui-ux/ — see ../OUTPUT.md


Step 0 — Determine Mode

ModeWhenOutput
audit"review my UI", file path given, pre-mergeFindings list + report file
polish-passscreenshot attached, "fix the hero", iterative tweaksMinimal code diff + short rationale
pre-shipbefore commit on UI-heavy changeAudit + pair with @ship-check if shipping

Ask if unclear:

  1. Scope — file, route, or component?
  2. Viewport — mobile / desktop / both?
  3. URL — local dev URL + route (e.g. http://localhost:3000/dashboard)
  4. Build or review only? — "don't code, plan only" → review only

Step 1 — Load Context

  1. Read principles.md
  2. Read the target file(s) or explore the route
  3. Note existing design system — reuse project components, tokens, patterns
  4. If screenshot provided — treat it as source of truth for what's wrong visually

Step 1b — Playwright Verification

Read playwright.md. Always run when a URL is reachable (unless review-only on code with no running app).

Use Playwright MCP when available; fallback to project Playwright tests or CLI.

Capture before screenshots + snapshot + console errors. Run interaction smoke checks for the scoped screen (scroll, input, menus, forms, CTAs).

Save artifacts under {output_dir}/screenshots/.

If Playwright cannot run, note why in the report and rely on code review + user screenshots — do not skip silently.


Step 2 — Review

Run review-checklist.md against scope and Playwright results.

For each finding:

  • Severity: Critical / Important / Suggestion
  • Location: file:line when reviewing code
  • Issue: one sentence
  • Fix: concrete — class change, component swap, copy rewrite, layout adjustment

Prioritize:

  1. Trust breakers (broken scroll, lost input, silent failures)
  2. Clarity (hierarchy, next action, copy)
  3. Polish (spacing, motion, micro-interactions)

Do not suggest gradients, glow, purple accents, or animation unless user asked.


Step 3 — Implement (unless review-only)

When building or polishing:

  • Minimal diff — fix what's broken, don't redesign the whole page
  • Match existing code style and component library
  • One primary change per iteration when user is in screenshot-driven loop
  • After edits, state what changed in plain language

Stack defaults from principles: Tailwind, cn(), accessible primitives, h-dvh, motion/react only when needed.

Re-run Playwright (Step 1b) after implementing — capture after screenshots and confirm failed interaction checks now pass.


Step 4 — Write Report (audit / pre-ship modes)

Fill report-template.md — the canonical record.

Path: {output_dir}/review-YYYY-MM-DD-[slug].md

Also generate a shareable HTML report when you have screenshots

When the audit produced Playwright screenshots (most audit/polish passes do), also emit an HTML version from report-template.html — it embeds the screenshots inline (incl. before/after pairs) so the user can read the whole review without opening files one by one.

  1. Copy report-template.html → {output_dir}/review-YYYY-MM-DD-[slug].html
  2. Replace every [[PLACEHOLDER]]; reference screenshots with the relative path screenshots/<file>.png so the report stays portable.
  3. Use the .grid2 before/after pattern for any fix you re-screenshotted.
  4. Open it for the user: open {output_dir}/review-...html (macOS).

Keep both in sync — the HTML is the shareable artifact, the .md is the record.

Update {output_dir}/index.md (link both formats):

# UI/UX Reviews

| Date | Scope | Verdict | Report |
|------|-------|---------|--------|
| YYYY-MM-DD | [scope] | [verdict] | [md](review-...md) · [html](review-...html) |

Step 5 — Output to User

  1. Verdict: Ship / Ship with fixes / Needs rework
  2. Top 3 issues (most impact first)
  3. Report path (if saved)
  4. Offer to implement fixes — or done if already implemented

For polish-pass: before/after summary in 2–3 bullets, no long essay.


Pair with other skills

  • @ship-check — run after UI changes before commit
  • @architecture-review — when UX change implies a product/architecture fork (e.g. new nav paradigm)

Edge Cases

  • User says "don't code" — audit + plan only
  • Conflicting project patterns — follow project, flag deviation from principles as Suggestion
  • Backend-only request — decline politely; this skill is UI/UX scoped
  • No running dev server — offer to start it, or audit code-only with note
  • Playwright MCP unavailable — use npx playwright test or document skip reason
  • Whole app redesign — ask for priority screen; do not boil the ocean in one pass

Invocation Examples

@ui-ux review the onboarding flow
@ui-ux audit http://localhost:3000/dashboard — desktop and mobile
polish the hero — dev server on :3000
ui pass before we ship
don't code — give me a plan for the dashboard layout

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.