Ywc Ui Ux Review

UI/UX Review — Hybrid (Code + Live UI)

Announce at start: "I'm using the ywc-ui-ux-review skill to combine static code analysis with live UI exploration."

Conduct a prioritized UI/UX review of a project by combining static code analysis with live UI exploration. Focus areas: Information Architecture and Visual Design. Output: a four-tier (Critical / High / Medium / Low) Markdown report.

Rationalization Defense

When tempted to skip a step, check this table first:

| Excuse | Reality | |---|---| | "Code-only review is enough, no need to launch the browser" | Hybrid means both. Static analysis cannot detect runtime layout shift, focus traps, or hover state breakage. | | "WCAG checks are exhaustive, skip them on internal tools" | Internal tools have employees with disabilities too. WCAG 2.2 AA is the minimum, not an opt-in. | | "Reduced motion / dark mode are edge cases, drop them" | These are accessibility requirements, not edge cases. Test both. | | "Severity feels Critical, mark it Critical regardless of impact" | Critical = blocks core flow or violates accessibility law. Reserve it. Inflated severity buries real critical findings. | | "Visual taste is subjective, do not flag design inconsistency" | Inconsistency in tokens (color, spacing, typography) is objective. Always flag. | | "Live exploration is risky on production, skip it" | Use a staging or preview URL. Skipping live exploration drops half the value of this skill. | | "IA and Visual Design share context, run them together" | They share evidence but use distinct checklists; parallel subagents each read only one checklist, reducing context load and preventing cross-domain finding drift. |

Violating the letter of these rules is violating the spirit. Static-only review with no live UI is design auditing on paper.

Triggers

• "Review the UI/UX of this project"
• "Audit usability of {feature/page}"
• Information Architecture or navigation evaluation
• Visual hierarchy / typography / spacing / color audit
• Pre-release UX checks against WCAG 2.2 AA
• Cross-cutting design review against an internal design system

Workflow

Run the six phases in order. Skip a phase only with explicit user consent.

Phase 1 — Scope & Context

Confirm the following with the user before any analysis. When ambiguous, ask:

• Target: pages, routes, or feature flows in scope
• Primary user journey: the one or two flows that matter most
• Stack: framework (React / Vue / Flutter / Astro / etc.) and design system in use
• Live URL: a running URL or local dev server (required for Phase 3)
• Internal design system: location of tokens, components, design guidelines (if any)

If no live URL is available, note it in the report and proceed with code-only review (degrade gracefully).

Phase 2 — Code Reconnaissance

Use Read, Grep, Glob to map:

• Routing tree and navigation structure (router config, route files)
• Top-level layouts and shell components
• Design tokens (colors, typography, spacing) — typically tokens.css, theme.ts, tailwind.config.*, *.tokens.json, design-system/
• Shared UI components and their variants
• Localization / i18n surface, if any

Capture findings as raw notes — do not score yet.

Phase 3 — Live UI Exploration (Chrome DevTools MCP)

Prefer Chrome DevTools MCP for inspection-focused analysis (token-efficient accessibility tree, automated audits, computed style access). Use Playwright MCP only when multi-step interaction automation is required.

Recommended tool sequence:

1. mcp__chrome-devtools__new_page or navigate_page — open the target URL
2. mcp__chrome-devtools__take_snapshot — get accessibility tree (token-efficient, structured)
3. mcp__chrome-devtools__take_screenshot — capture visual evidence per breakpoint
4. mcp__chrome-devtools__resize_page — repeat for 360 / 768 / 1280 / 1920
5. mcp__chrome-devtools__lighthouse_audit — automated accessibility / performance scoring
6. mcp__chrome-devtools__list_console_messages — surface runtime errors
7. mcp__chrome-devtools__evaluate_script — pull computed styles, contrast, focus chain when needed

For each piece of evidence record: URL, breakpoint, screenshot reference, snapshot excerpt.

Phase 4 — Per-Domain Review (Parallel)

Use the Task tool to spawn 2 Sonnet subagents in parallel. Pass each subagent the code reconnaissance notes from Phase 2 and the live UI evidence from Phase 3:

| Subagent | Model | Reference | |---|---|---| | IA Reviewer | sonnet | references/ia-checklist.md | | Visual Design Reviewer | sonnet | references/visual-design-checklist.md |

Each subagent returns findings with:

• Concrete location (file path + line number, OR screen + selector)
• Observed behavior
• Expected behavior (per heuristic)
• Preliminary heuristic citation

Phase 4b — Merge & Cross-Check

Combine findings from both subagents. Cross-check each finding against references/heuristics-combined.md to attach an authoritative citation (Nielsen / WCAG / Material / HIG / internal design system). Deduplicate findings that share the same location.

Phase 5 — Severity Triage

Load references/severity-rubric.md and classify every finding into one of: Critical / High / Medium / Low. The rubric is the single source of truth — do not invent custom levels.

Phase 6 — Report Generation

Generate the report using assets/report-template.md as the structural template. Fill all placeholders. Default output path: claudedocs/ui-ux-review-{YYYY-MM-DD}.md unless the user specifies otherwise.

Output format — Default is a Markdown report. When the user passes --format html (parsed from $ARGUMENTS), emit a self-contained HTML report (claudedocs/ui-ux-review-{YYYY-MM-DD}.html) instead, following [html-output.md](../references/html-output.md): four severity tabs, color-coded finding cards, screenshots from Phase 3 embedded inline as data: URIs, and a Copy as Markdown button. The Markdown surface is preserved inside the file, so downstream integration is unaffected.

Reference Files

| File | When to load | |---|---| | references/ia-checklist.md | Phase 4, IA review | | references/visual-design-checklist.md | Phase 4, Visual Design review | | references/heuristics-combined.md | Phase 4b, attaching authoritative citation | | references/severity-rubric.md | Phase 5, severity classification | | assets/report-template.md | Phase 6, report scaffolding |

Output Rules

• Every finding cites a heuristic (Nielsen #N / WCAG SC X.X.X / Material spec / HIG section / internal token name)
• Every finding has a location (file:line OR screen:selector)
• Every finding has a concrete recommendation — code snippet or design change, not just "improve UX"
• Group findings under the four severity tiers exactly as the template defines
• Lead the report with an executive summary: count per tier, top 3 systemic patterns, top 5 recommended actions
• Keep tone factual and respectful — review the work, not the people

Advisor Escalation Policy

Budget: up to 2 Opus advisor calls per invocation.

Escalate to an Opus advisor only when the executor cannot resolve the severity classification from references/severity-rubric.md alone. Two conditions qualify:

| Condition | Example | |---|---| | Borderline Critical vs High | An accessibility issue blocks assistive-technology users on a primary flow, but only under a specific screen-reader / browser combination that the rubric does not explicitly address — both Critical and High are defensible | | Heuristic conflict | Nielsen's "Visibility of system status" (#1) and Apple HIG's "Clarity" principle produce opposite recommendations for the same UI element (e.g., a persistent loading indicator that aids status visibility but creates visual noise per HIG clarity) |

For all other borderline cases — High vs Medium, Medium vs Low, uncertain evidence from code-only analysis — choose the more conservative (lower) tier and add a brief inline note explaining the uncertainty. Do not escalate these to Opus.

Boundaries

Will:

• Review IA, Visual Design, accessibility, and usability of the target project
• Combine static code evidence with live UI evidence
• Produce a prioritized, citation-backed Markdown report

Will Not:

• Re-design or refactor code on the user's behalf (review only — implementation is a separate task)
• Fabricate findings without code or runtime evidence
• Replace formal user testing with real users
• Score subjective beauty — every judgment is anchored to a heuristic

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yongwoon
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.