Stats
Actions
Tags
From ywc-agent-toolkit
Combines static code analysis with live UI exploration (Chrome DevTools) to audit information architecture, visual design, usability, and accessibility.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ywc-agent-toolkit:ywc-ui-ux-reviewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Announce at start:** "I'm using the ywc-ui-ux-review skill to combine static code analysis with live UI exploration."
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.
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.
Run the six phases in order. Skip a phase only with explicit user consent.
Confirm the following with the user before any analysis. When ambiguous, ask:
If no live URL is available, note it in the report and proceed with code-only review (degrade gracefully).
Use Read, Grep, Glob to map:
tokens.css, theme.ts, tailwind.config.*, *.tokens.json, design-system/Capture findings as raw notes — do not score yet.
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:
mcp__chrome-devtools__new_page or navigate_page — open the target URLmcp__chrome-devtools__take_snapshot — get accessibility tree (token-efficient, structured)mcp__chrome-devtools__take_screenshot — capture visual evidence per breakpointmcp__chrome-devtools__resize_page — repeat for 360 / 768 / 1280 / 1920mcp__chrome-devtools__lighthouse_audit — automated accessibility / performance scoringmcp__chrome-devtools__list_console_messages — surface runtime errorsmcp__chrome-devtools__evaluate_script — pull computed styles, contrast, focus chain when neededFor each piece of evidence record: URL, breakpoint, screenshot reference, snapshot excerpt.
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:
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.
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.
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: 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.
| 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 |
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.
Will:
Will Not:
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub yongwoon/ywc-agent-toolkit