test-ui
Multi-viewport UI testing with screenshots, visual regression detection, and accessibility audits
Best use case
test-ui is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Multi-viewport UI testing with screenshots, visual regression detection, and accessibility audits
Teams using test-ui should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/test-ui/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How test-ui Compares
| Feature / Agent | test-ui | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Multi-viewport UI testing with screenshots, visual regression detection, and accessibility audits
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Test-UI Skill
## Purpose
Systematically test user interfaces across viewports, accessibility standards, and interaction patterns. This skill uses visual testing (screenshots), automated accessibility auditing, and interaction verification to catch UI problems that unit tests miss.
UI bugs are user-facing bugs. They are the first thing users see and the last thing developers test. This skill closes that gap.
## Workflow
### Phase 1: Test Setup
1. **Identify the test target**:
- URL of a running application
- Specific page or route
- Component in a Storybook or dev server
2. **Define viewport matrix** (default set):
| Name | Width | Height | Device Class |
|------|-------|--------|-------------|
| Mobile S | 320 | 568 | iPhone SE |
| Mobile M | 375 | 667 | iPhone 8 |
| Mobile L | 414 | 896 | iPhone 11 |
| Tablet | 768 | 1024 | iPad |
| Desktop | 1280 | 800 | Laptop |
| Desktop L | 1920 | 1080 | Full HD |
3. **Set up the browser** using Playwright MCP:
- Navigate to the target URL
- Wait for page load completion
- Dismiss any modals/cookie banners that obscure content
### Phase 2: Visual Testing
4. **For each viewport in the matrix**:
a. Resize the browser to the viewport dimensions
b. Wait for layout to settle (resize can trigger animations)
c. Take a full-page screenshot
d. Take a viewport-only screenshot (above the fold)
e. Record any visual anomalies observed:
- Text overflow / truncation
- Element overlap
- Broken layout (flex/grid issues)
- Missing images or icons
- Inconsistent spacing
- Z-index conflicts (elements stacking incorrectly)
5. **Capture key states** (if interactive elements exist):
- Default state
- Hover state (for interactive elements)
- Focus state (keyboard navigation)
- Active/pressed state
- Error state (form validation)
- Loading state (if applicable)
- Empty state (if applicable)
### Phase 3: Accessibility Audit
6. **Evaluate against WCAG 2.1 AA criteria**:
**Perceivable**:
- [ ] All images have alt text (or are marked decorative)
- [ ] Color contrast meets 4.5:1 for text, 3:1 for UI elements
- [ ] Content is readable without color alone (not just red/green indicators)
- [ ] Text can be resized to 200% without loss of content
- [ ] No content relies solely on sensory characteristics (shape, size, position)
**Operable**:
- [ ] All interactive elements are keyboard accessible (Tab, Enter, Space, Escape)
- [ ] Focus order is logical and follows visual order
- [ ] Focus indicators are visible (not just browser default)
- [ ] No keyboard traps (can Tab out of every element)
- [ ] Sufficient click/touch target size (minimum 44x44px)
- [ ] Skip navigation link available (for pages with nav)
**Understandable**:
- [ ] Page language is set (`<html lang="en">`)
- [ ] Form inputs have visible labels
- [ ] Error messages are clear and associated with their fields
- [ ] Navigation is consistent across pages
**Robust**:
- [ ] Semantic HTML is used (headings, landmarks, lists)
- [ ] ARIA attributes are correct (roles, states, properties)
- [ ] Heading hierarchy is logical (no skipped levels)
7. **Run automated accessibility check** using browser evaluation:
```javascript
// Check for missing alt text
document.querySelectorAll('img:not([alt])');
// Check for empty buttons/links
document.querySelectorAll('a:empty, button:empty');
// Check heading hierarchy
document.querySelectorAll('h1, h2, h3, h4, h5, h6');
```
### Phase 4: Responsive Testing
8. **Check layout integrity across viewports**:
- Does content reflow properly at each breakpoint?
- Are there horizontal scrollbars on mobile?
- Does navigation collapse to a mobile menu?
- Are touch targets large enough on mobile (44x44px minimum)?
- Does text remain readable on all sizes (no text smaller than 14px)?
- Do images scale appropriately?
- Are interactive elements reachable without hover (for touch devices)?
9. **Check breakpoint transitions**:
- Are there awkward intermediate states between breakpoints?
- Does content jump or flash during resize?
- Are there viewport ranges where the layout breaks?
### Phase 5: Interaction Testing
10. **Test interactive elements** (using Playwright):
- Click buttons and links -- do they work?
- Fill form fields -- do they accept input?
- Test dropdown/select menus -- do they open and close?
- Test modals/dialogs -- do they open, close, and trap focus?
- Test navigation -- do links go to the right place?
- Test form submission -- does it validate and submit?
11. **Test keyboard navigation**:
- Tab through the page -- is the order logical?
- Enter/Space on buttons -- do they activate?
- Escape on modals -- do they close?
- Arrow keys on menus/selects -- do they navigate?
### Phase 6: Report
12. **Produce the UI test report** using the template below.
13. **Prioritize findings** by user impact.
## UI Test Report Template
```markdown
# UI Test Report
## Target
**URL**: [url]
**Date**: [date]
**Viewports tested**: [list]
---
## Visual Summary
| Viewport | Screenshot | Issues |
|----------|-----------|--------|
| Mobile (375px) | [screenshot ref] | [count] issues |
| Tablet (768px) | [screenshot ref] | [count] issues |
| Desktop (1280px) | [screenshot ref] | [count] issues |
## Issues Found
### Critical (Blocks Usage)
#### [V1] [Title]
- **Viewport**: [affected viewports]
- **Description**: [what is wrong]
- **Expected**: [correct behavior]
- **Screenshot**: [reference]
### Major (Degrades Experience)
#### [V2] [Title]
...
### Minor (Polish)
#### [V3] [Title]
...
---
## Accessibility Audit
### Violations
| Rule | Impact | Elements | Fix |
|------|--------|----------|-----|
| [rule] | [critical/serious/moderate] | [count] | [recommendation] |
### Passes
- [count] rules passing
---
## Responsive Behavior
| Breakpoint | Layout | Navigation | Typography | Media |
|-----------|--------|------------|------------|-------|
| 320px | OK/Issue | OK/Issue | OK/Issue | OK/Issue |
| 768px | OK/Issue | OK/Issue | OK/Issue | OK/Issue |
| 1280px | OK/Issue | OK/Issue | OK/Issue | OK/Issue |
## Interaction Results
| Element | Click | Keyboard | Focus | Hover |
|---------|-------|----------|-------|-------|
| [button/link] | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail |
---
## Recommendations
1. **[Highest priority]**: [action]
2. **[Second priority]**: [action]
3. ...
```
## Usage
### Full UI test
```
/test-ui http://localhost:3000
```
### Specific page
```
/test-ui http://localhost:3000/checkout
```
### Accessibility only
```
/test-ui accessibility http://localhost:3000
```
### Responsive only
```
/test-ui responsive http://localhost:3000/dashboard
```
### Specific viewports
```
/test-ui http://localhost:3000 --viewports mobile,desktop
```
## Examples
### Example: Finding a responsive issue
**Test**: Homepage at 375px width
**Finding**: Hero section text overflows container, creating horizontal scrollbar
**Root cause**: Fixed width of 500px on hero text container instead of max-width
**Fix recommendation**: Change `width: 500px` to `max-width: 100%`
### Example: Accessibility finding
**Test**: Login form
**Finding**: Password field has no visible label (only placeholder text)
**Impact**: Screen reader users cannot identify the field; placeholder disappears on focus
**Fix recommendation**: Add a visible `<label>` element associated with the input via `htmlFor`
### Example: Interaction issue
**Test**: Mobile navigation menu
**Finding**: Hamburger menu opens on click but cannot be closed with keyboard (Escape key does not work)
**Impact**: Keyboard users are trapped in the menu
**Fix recommendation**: Add Escape key handler to close the menu and return focus to the trigger button
## Guidelines
- **Test real viewports, not just desktop** -- More than half of web traffic is mobile. Test mobile first.
- **Accessibility is not optional** -- WCAG AA compliance is a legal requirement in many jurisdictions and a moral one everywhere.
- **Screenshots are evidence** -- Always include screenshots in reports. They are worth a thousand words.
- **Test the flow, not just the page** -- Users do not look at pages; they complete tasks. Test the full flow.
- **Focus states matter** -- If you cannot see where keyboard focus is, the site is broken for keyboard users.
- **Touch targets must be large enough** -- 44x44px minimum. Fingers are not mouse cursors.
- **Do not test with only Chrome** -- If possible, note that cross-browser testing should be done separately.
- **Color is not the only indicator** -- Always pair color with text, icons, or patterns for status indicators.
- **Test with real content** -- Lorem ipsum hides overflow issues. Use realistic text lengths.Related Skills
Vitest
> Blazing fast unit testing powered by Vite — Jest-compatible API, native ESM, TypeScript.
testing-toolkit
Unified testing methodology toolkit — Testing Library (accessible queries, user-event, component testing), unit/integration/e2e/property-based testing patterns, test strategy design (pyramid/trophy/diamond, coverage goals), test fixtures (factories, builders, seeders, snapshots), API testing (Supertest, contract testing, endpoint validation). Keeps runtime-specific runners (vitest/playwright/cypress/promptfoo) separate.
test
Test planning, generation, and execution -- unit, integration, and end-to-end testing workflows
load-testing
Load testing with k6, Artillery, Locust — traffic simulation, performance baselines, and stress testing.
contract-testing
Consumer-driven contract testing with Pact, schema validation, and API compatibility verification.
accessibility-testing
Accessibility testing with axe-core, pa11y, Lighthouse, screen reader testing, and WCAG compliance verification
ab-test-generator
Generate A/B test variants for affiliate content. Triggers on: "create A/B test", "test my headline", "optimize my CTA", "generate variants", "split test ideas", "improve click-through rate", "test my landing page copy", "headline alternatives", "CTA variations", "which version is better", "optimize conversions", "test my email subject line", "compare approaches".
ultrathink
UltraThink Workflow OS — 4-layer skill mesh with persistent memory and privacy hooks for complex engineering tasks. Routes prompts through intent detection to activate the right domain skills automatically.
ultrathink_review
Multi-pass code review powered by UltraThink's quality gate — checks correctness, security (OWASP), performance, readability, and project conventions in a single structured pass.
ultrathink_memory
Persistent memory system for UltraThink — search, save, and recall project context, decisions, and patterns across sessions using Postgres-backed fuzzy search with synonym expansion.
ui-design
Comprehensive UI design system: 230+ font pairings, 48 themes, 65 design systems, 23 design languages, 30 UX laws, 14 color systems, Swiss grid, Gestalt principles, Pencil.dev workflow. Inherits ui-ux-pro-max (99 UX rules) + impeccable-frontend-design (anti-AI-slop). Triggers on any design, UI, layout, typography, color, theme, or styling task.
Zod
> TypeScript-first schema validation with static type inference.