| name | test-heatmap |
| description | Analyze attention patterns, visual hierarchy, and interaction prediction. Use when user wants to analyze UX layout, visual hierarchy, CTA placement, click target analysis, or attention scoring. |
| allowed-tools | Bash(playwright-cli:*) Bash(npx:*) Bash(mkdir:*) |
Attention & Interaction Prediction
Run 24 UX analysis test cases across 3 parallel agents covering layout patterns, interaction mapping, and attention scoring. Uses computational analysis of element positions, sizes, and styles to predict user attention patterns.
Setup
URL="${ARGUMENTS:-http://localhost:3000}"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTDIR="test-results/test-heatmap/$TIMESTAMP"
mkdir -p "$OUTDIR/screenshots" "$OUTDIR/snapshots" "$OUTDIR/traces"
Before running, verify prerequisites per references/prerequisites.md.
Parallel Execution — 3 Subagents
Agent 1: Layout (-s=heat-layout)
Analyzes layout patterns and visual hierarchy.
playwright-cli -s=heat-layout open "$URL"
playwright-cli -s=heat-layout tracing-start
playwright-cli -s=heat-layout screenshot --filename="$OUTDIR/screenshots/layout-full.png"
playwright-cli -s=heat-layout snapshot --filename="$OUTDIR/snapshots/layout-initial.yaml"
Test Cases:
| TC | Test | How to Check |
|---|
| TC-HM1 | F-pattern compliance | run-code to map element positions — check if primary content follows F-shape: strong top horizontal bar, left-aligned content, decreasing right engagement. Score elements by (y-position × x-position) weight |
| TC-HM2 | Z-pattern for landing pages | run-code to check if hero section follows Z: top-left (logo/brand) → top-right (nav/CTA) → bottom-left (features) → bottom-right (CTA). Analyze element positions in quadrants |
| TC-HM3 | Above-fold content percentage | run-code to measure viewport height, calculate percentage of critical content (h1, CTAs, hero) visible without scrolling |
| TC-HM4 | Visual hierarchy scoring | run-code to rank elements by: (fontSize * fontWeight/400) × contrastRatio × (1/distanceFromTop). Output ranked list of attention-grabbing elements |
| TC-HM5 | Whitespace balance | run-code to divide viewport into grid cells, calculate content density per cell. Flag overcrowded cells (>80% filled) and empty cells (>90% empty in content areas) |
| TC-HM6 | Grid alignment | run-code to collect left-edge x-positions of content blocks. Check if they cluster around consistent grid lines (within ±4px) |
| TC-HM7 | Gutenberg diagram | run-code to divide viewport into 4 quadrants. Verify: top-left (primary optical area) has logo/headline, bottom-right (terminal area) has CTA |
| TC-HM8 | Reading flow | run-code to order content blocks by position. Verify top→bottom, left→right flow for LTR pages. Check dir attribute for RTL |
playwright-cli -s=heat-layout tracing-stop
playwright-cli -s=heat-layout close
Agent 2: Interaction (-s=heat-interaction)
Analyzes click targets and interaction mapping.
playwright-cli -s=heat-interaction open "$URL"
playwright-cli -s=heat-interaction tracing-start
Test Cases:
| TC | Test | How to Check |
|---|
| TC-HM9 | CTA prominence — largest/most contrasting | run-code to find all interactive elements, rank by: area × contrastRatio. Primary CTA should be #1 or #2 |
| TC-HM10 | CTA positioning — above fold, terminal area | run-code to get primary CTA bounding box, verify it's within viewport height and in center or bottom-right quadrant |
| TC-HM11 | Fitts's Law — large + near cursor | run-code to measure button sizes. Frequently-used buttons (submit, CTA, nav) should be larger than utility buttons (settings, close) |
| TC-HM12 | Click target density — not overcrowded | run-code to find clusters of interactive elements. Flag areas where >5 interactive elements within 100x100px |
| TC-HM13 | Click target dead zones | run-code to find large areas (>200x200px) between interactive elements with no clickable targets |
| TC-HM14 | Button hierarchy — visually distinct | run-code to categorize buttons by styling (background-color, border, size). Verify primary/secondary/tertiary are visually differentiated |
| TC-HM15 | Interactive element spacing ≥8px | run-code to measure gaps between adjacent interactive elements. Flag gaps <8px |
| TC-HM16 | Hover areas match visual size | run-code to compare element visible size vs clickable area (padding, computed dimensions). Flag mismatches |
playwright-cli -s=heat-interaction tracing-stop
playwright-cli -s=heat-interaction close
Agent 3: Attention (-s=heat-attention)
Scores attention distribution and detects dead zones.
playwright-cli -s=heat-attention open "$URL"
playwright-cli -s=heat-attention tracing-start
Test Cases:
| TC | Test | How to Check |
|---|
| TC-HM17 | Color contrast attention | run-code to rank elements by contrast ratio vs their background. Verify highest-contrast elements are important content (not decorative) |
| TC-HM18 | Size-based attention | run-code to rank elements by visual area. Verify largest elements are primary content (hero, h1, CTA), not ads or decorative |
| TC-HM19 | Animation attention | run-code to find elements with CSS animation/transition. Verify animated elements are intentional attention-grabbers (loading, CTA pulse), not distracting (ads, decoration) |
| TC-HM20 | Isolation effect — CTA whitespace | run-code to measure whitespace around primary CTA. Verify ≥24px padding on all sides from other content |
| TC-HM21 | Image focal points toward CTA | run-code to check hero image position relative to CTA. Verify image is adjacent to (not covering) CTA |
| TC-HM22 | Competing elements — no dual CTAs | run-code to find equally-styled primary CTAs in same viewport section. Flag if 2+ primary CTAs compete |
| TC-HM23 | Banner blindness zones | run-code to check if critical content is placed in typical ad zones: right sidebar 300px, top banner 90px, bottom banner. Flag important content in these zones |
| TC-HM24 | Scroll depth prediction | run-code to calculate page height vs viewport. If page is >3x viewport, verify most important content is in top 50% |
playwright-cli -s=heat-attention tracing-stop
playwright-cli -s=heat-attention close
Fix Loop
After execution, if any tests failed, follow the fix loop process in references/fix-loop.md.
Max 3 attempts. Only re-run failed test cases.
Include fix attempt history in the report.
Report Generation
After all 3 agents complete, merge results into $OUTDIR/report.md.
Include an attention map summary:
- Visual hierarchy ranking: Top 10 elements by predicted attention
- CTA effectiveness score: Position × size × contrast
- Problem areas: Dead zones, competing elements, misplaced content
- Recommendations: Specific layout adjustments with reasoning
Group results:
- Layout Patterns (TC-HM1 through TC-HM8)
- Interaction Mapping (TC-HM9 through TC-HM16)
- Attention Scoring (TC-HM17 through TC-HM24)
Cleanup
playwright-cli -s=heat-layout close 2>/dev/null
playwright-cli -s=heat-interaction close 2>/dev/null
playwright-cli -s=heat-attention close 2>/dev/null
