Ui Responsive Testing Skill

UI Responsive Testing Skill

Load this skill when the user explicitly names ui-responsive-testing-skill or asks for responsive UI QA generation.

Purpose

Generate a focused, repeatable Playwright QA spec for one URL. The generated spec validates:

1. Runtime health. 2. Visible main-content links. 3. Main-content buttons and CTAs. 4. Page sections. 5. Images, icons, and media. 6. Layout integrity screenshots and AI review hooks.

Never run the generated Playwright tests as part of this skill. Provide commands with --workers=1 for the user to run.

Required References

Read only the references needed for the current task:

• reference/test-matrix.md - exact six-test matrix.
• reference/helpers.md - inline helper requirements.
• reference/reporting.md - result file, screenshots, and AI hook status behavior.
• reference/visual-review.md - monitor handoff and strict spelling review.
• reference/non-negotiable-rules.md - scroll, grouping, exclusion, hook, and spelling rules.
• reference/spec-self-check.md - pre-completion checklist.
• reference/platform-adapters.md - WordPress, Elementor, and similar page adapters.
• templates/playwright-spec-skeleton.ts - canonical spec shape.

Non-Negotiable Behavior

• Generate exactly six grouped tests per enabled viewport: runtime health, links, CTAs, sections, media, and layout integrity.
• Group tests under test.describe(vp.name, ...) for each enabled viewport. Do not flatten viewport tests at file scope.
• Put test.describe.configure({ mode: 'serial' }) at file top.
• Keep all helpers inline in tests/ui-responsive/[page-slug].spec.ts.
• Exclude header, nav, mobile menu, footer, and their descendants from validation, screenshots, spelling, and AI review.
• Use classList.contains() in ancestor exclusion checks. Do not use substring checks against className.
• Call ensureInViewport() before every check, highlight, click, screenshot, or section capture.
• Section checks must draw a visible highlightSectionBand and overlay SECTION n/N - {label}.
• Layout tests must capture content-zone screenshot slices, log [QA_AI_ANALYSIS_READY], and write pending-ai-review hook rows.
• After the monitor reviews a viewport, it must update that processed hook row from pending-ai-review to ai-review-completed.

Do not generate removed v1 categories: forms, dynamic widgets, page rendering/framework integrity, or accessibility smoke tests.

Workflow

1. Live Inventory

Require a full https:// URL. Derive PAGE_SLUG from the last path segment, using home for the root path.

Confirm HTTP 2xx before generating files. Record:

• title
• meta description when available
• H1 text and count
• platform signals
• main CTA hints
• main-content image/media count
• section hints

If the URL is unreachable, report the status and stop.

2. Generate Or Update Spec

Write tests/ui-responsive/[page-slug].spec.ts.

The spec must:

• Use the exact six-test matrix.
• Keep runtime-discovered links, CTAs, sections, and media as plain objects.
• Track LAYOUT_HOOK_VIEWPORTS after successful screenshot capture.
• Append to test-results/[page-slug]/test-result.md.
• Write layout screenshots to test-results/[page-slug]/screenshots/.
• Include Target URL: [url] in each test run block.
• Use ai-review-completed for already reviewed viewports and pending-ai-review for new hooks.

Create tests/ui-responsive/qa-run-config.json only if missing. Devices default to false; preserve existing device settings when updating an existing config.

3. Self-Check

Before completion, check the generated spec against reference/spec-self-check.md.

At minimum verify:

• serial mode exists
• each enabled viewport has six tests
• no removed v1 categories exist
• ensureInViewport is used
• exclusion uses classList.contains
• layout test logs AI hooks
• appendResults() writes hook rows from LAYOUT_HOOK_VIEWPORTS
• user commands include --workers=1

Use playwright test [spec] --list only as a non-executing parse/list check.

4. Monitor Handoff

After spec generation or update, spawn or reuse qa-visual-review-monitor from agents/qa-visual-review-monitor.toml.

Use this instruction:

Use the qa-visual-review-monitor monitor agent to watch test-results/ for pending-ai-review hooks. Perform a strict spelling audit. Do not rely on any previous Spelling Check section. Read every screenshot slice in order, then do a second word/token pass for small copy, cards, pills, buttons, repeated boundary text, missing spaces, merged words, odd capitalization, transpositions, and near-word errors. Report every confirmed typo with all visible slice names. After appending review sections for a viewport, update that processed hook row from pending-ai-review to ai-review-completed; do not rewrite any other hook rows or prior review sections.

Completion Output

Report:

• files changed
• URL and slug
• enabled viewports
• inventory counts
• six tests per viewport
• spec path
• result file path
• monitor status
• run commands, not executed

Examples

Use ui-responsive-testing-skill for https://example.com/case-study/

Use ui-responsive-testing-skill to generate desktop and mobile tests for https://example.com/about/

After generation:

# Edit tests/ui-responsive/qa-run-config.json — enable desktop: true
npx playwright test tests/ui-responsive/case-study.spec.ts --workers=1 --headed

Then invoke monitor:

Use the qa-visual-review-monitor monitor agent to process pending AI review hooks. Perform a strict spelling audit with both a line pass and a word/token pass.

If a previous spelling review missed issues:

Use the qa-visual-review-monitor monitor agent defined in agents/qa-visual-review-monitor.toml. A previous AI review exists, but the user reports it missed spelling mistakes. Perform a strict supplemental spelling audit, not a normal first-pass review. Append only Supplemental Spelling Audit, Supplemental UI Suggestions, and Supplemental AI Review Completion Note at the bottom of test-result.md.

Helpers Contract (inline in every generated spec)

Viewport gate (required before interaction)

async function ensureInViewport(
  page: Page,
  target: Locator | { scrollY: number },
): Promise<void> {
  if ('scrollY' in target) {
    await page.evaluate((y) => window.scrollTo({ top: Math.max(0, y - 80), behavior: 'instant' }), target.scrollY);
    await page.waitForTimeout(150);
    return;
  }
  await target.scrollIntoViewIfNeeded({ timeout: 8000 }).catch(async () => {
    const box = await target.boundingBox();
    if (box) {
      await page.evaluate((y) => window.scrollTo({ top: Math.max(0, y - 80), behavior: 'instant' }), box.y);
    }
  });
  await page.waitForTimeout(150);
  const box = await target.boundingBox();
  if (box) {
    const vh = page.viewportSize()?.height ?? 900;
    const inView = box.y >= -20 && box.y + box.height <= vh + 40;
    if (!inView) {
      await page.evaluate((y) => window.scrollTo({ top: Math.max(0, y - 80), behavior: 'instant' }), box.y);
      await page.waitForTimeout(150);
    }
  }
}

Rule: Every link, button, image/media target, and section check calls ensureInViewport immediately before highlight or click.

Section band highlight (required for test 4)

async function highlightSectionBand(
  page: Page,
  top: number,
  height: number,
  label: string,
): Promise<void> {
  await page.evaluate(({ t, h, lbl }) => {
    document.getElementById('qa-section-band')?.remove();
    document.getElementById('qa-section-label')?.remove();
    const band = document.createElement('div');
    band.id = 'qa-section-band';
    const rect = { top: t, height: Math.max(h, 120) };
    Object.assign(band.style, {
      position: 'absolute',
      left: '0',
      width: '100%',
      top: `${rect.top}px`,
      height: `${rect.height}px`,
      border: '3px dashed #00e676',
      background: 'rgba(0,230,118,0.08)',
      pointerEvents: 'none',
      zIndex: '2147483644',
      boxSizing: 'border-box',
    });
    const tag = document.createElement('div');
    tag.id = 'qa-section-label';
    tag.textContent = `▶ ${lbl}`;
    Object.assign(tag.style, {
      position: 'absolute',
      left: '12px',
      top: `${Math.max(0, rect.top - 28)}px`,
      background: '#00e676',
      color: '#000',
      padding: '4px 10px',
      fontWeight: '700',
      fontSize: '13px',
      zIndex: '2147483645',
      pointerEvents: 'none',
      borderRadius: '4px',
    });
    document.body.appendChild(band);
    document.body.appendChild(tag);
  }, { t: top, h: height, lbl: label });
  if (VISUAL_MODE) await page.waitForTimeout(700);
}

async function clearSectionBand(page: Page): Promise<void> {
  await page.evaluate(() => {
    document.getElementById('qa-section-band')?.remove();
    document.getElementById('qa-section-label')?.remove();
  });
}

Exclusion (Rule 1)

Use `classList.contains()` only in ancestor walks. Early exit at content roots:

id === 'main' || id === 'av-content' || id === 'content' || id === 'page-content'

Never String(className).toLowerCase().includes('av-header').

Other required helpers

• Visual: showQaOverlay, highlightElement (via locator.evaluate), clearHighlight, showPointerAt, visuallyClick (calls ensureInViewport first)
• Links: collectNormalLinks, safeClickAndVerifyTarget (ensureInViewport before click)
• Layout: detectStickyOverlays, showContentAreaHighlight, captureLayoutSlices (content-zone clip only)
• Metadata: sanitizeFailureReason, recordCheckResult, classifyLink, isInsideExcludedRegion (locator.evaluate)

Data collection

• Links/CTAs: single page.evaluate → plain objects; never hold Locator[] across page.goto.
• Internal links: page.goto(href) after ensureInViewport, not stale locator click.
• Images: locator.evaluate on HTMLImageElement — no elementHandle().

Section selectors

const SECTION_SELECTORS = [
  'section',
  '[class*="avia-section"]',
  '[class*="elementor-section"]',
  '.wp-block-group',
  '[data-section-id]',
];

Deduplicate with 50px Y-bucket. Store { label, top, height, populated } for scroll/highlight.

Non-Negotiable Rules

These rules replace the legacy responsive QA workflow files. They are skill reference material, not command execution policy.

Scroll Into Viewport

Before highlighting, clicking, asserting visibility, or capturing a target element:

1. Call ensureInViewport(page, locator) or ensureInViewport(page, { scrollY }) for sections. 2. Verify the target intersects the viewport and retry scrolling when needed. 3. Only then call highlightElement, visuallyClick, safeClickAndVerifyTarget, or record pass/fail.

Section tests must use highlightSectionBand plus overlay SECTION n/N - {label} after scrolling to section.top.

Never click or judge off-screen elements.

Device Grouping

For each enabled viewport/device, wrap its tests in a device-specific describe block:

for (const vp of enabledViewports()) {
  test.describe(vp.name, () => {
    test('page load and runtime health', async ({ page }) => {
      // ...
    });
  });
}

Desktop tests must live under the desktop block, tablet tests under the tablet block, and mobile tests under the mobile block.

Do not rely on flat test names such as desktop - page load and runtime health as the only grouping.

AI Review Hooks

• File top: test.describe.configure({ mode: 'serial' }).
• Track LAYOUT_HOOK_VIEWPORTS.add(viewport) after layout screenshots succeed.
• appendResults() must write ### AI Review Hooks from LAYOUT_HOOK_VIEWPORTS; never write an empty table when layout ran.
• After the monitor appends review sections for a viewport, it must update that processed hook row from pending-ai-review to ai-review-completed.
• Layout test logs [QA_AI_ANALYSIS_READY] JSON to stdout.
• Users run with --workers=1.
• After spec generation, spawn qa-visual-review-monitor.
• If the user reports a prior spelling review missed issues, spawn or perform a strict supplemental spelling audit using visual-review.md, even when no pending hook remains.

Strict Spelling Audit

When processing AI review hooks, the monitor must do two proofreading passes:

1. Read every visible main-content line in every screenshot slice. 2. Re-scan every word/token for missing letters, extra letters, transpositions, merged words, missing spaces, odd in-word capitalization, malformed common phrases, and near-word errors.

Do not rely on an earlier Spelling Check as complete. If a stricter re-audit is requested after an existing review, append ## Supplemental Spelling Audit - [viewport] and related supplemental sections at the bottom of the same test-result.md.

Deduplicate repeated boundary text, but list all slices where the issue is visible.

After review sections are appended, update only the processed hook row status to ai-review-completed. Do not rewrite result rows, prior reviews, screenshots, specs, or site source.

If the user says the review missed spelling mistakes, run the supplemental spelling audit even if the hook was already processed. The parent prompt must say "strict supplemental spelling audit" and include the workspace, result file, ordered screenshot range, and the exact supplemental section names.

The audit must cover hero copy, section intro text, small cards, outcome cards, labels/pills, CTA text, repeated boundary text, and low-contrast body copy. Confirmed missing-letter and near-word errors such as senter, error-prne, gro, se, developrs, competits, and sciuence must be reported when visible in context.

Use a consistent spelling table:

| Slice | Text | Issue | Suggested correction | Confidence |
| --- | --- | --- | --- | --- |

The monitor should internally build a candidate list before writing the table, but append only confirmed issues.

Header and Footer Exclusion

In every page.evaluate ancestor walk and isInsideExcludedRegion, use classList.contains():

const cl = node.classList;
cl.contains('av-header'); // correct
// wrong: String(node.className).toLowerCase().includes('av-header')

Early exit inside content: id === 'main' || id === 'av-content' || id === 'content' || id === 'page-content'.

Exclude header, nav, footer, mobile-menu, and all descendants. Main-content CTAs and links remain in scope.

Spec Generation

When generating or updating specs under tests/ui-responsive/:

1. Read ui-responsive-testing-skill/SKILL.md and linked reference/ files. 2. Live inventory the URL; do not invent page facts. 3. Generate exactly six grouped tests: runtime health, links, CTAs, sections, media, and layout integrity. 4. Inline all helpers; use templates/playwright-spec-skeleton.ts structure. 5. Run spec-self-check.md before completion. 6. Spawn qa-visual-review-monitor after generation. 7. Spawn supplemental mode, not generic monitor mode, when a prior AI spelling review is challenged. 8. Do not run Playwright; provide commands with --workers=1 only.

Platform Adapters (optional fallbacks)

Detect first; apply only matching adapter. Generic selectors always win.

Detection

Elementor media (important)

Many Elementor pages have no main img. Include:

.elementor-section img, .elementor-widget-image img, .elementor-widget-image img

Exclusion

Platform adapters do not override header/footer exclusion rules.

Reporting and AI Hooks (v2)

Paths

test-results/[page-slug]/test-result.md     # single append-only ledger
test-results/[page-slug]/screenshots/     # [viewport]_slice_NNN.png
.playwright-output/                        # Playwright artifacts (not test-results)

Parallel run fix (required)

Playwright parallel workers split afterAll and drop AI hooks for tests that ran in other workers.

Generated specs must include at file top:

test.describe.configure({ mode: 'serial' });

Document that users run with:

npx playwright test tests/ui-responsive/[page-slug].spec.ts --workers=1

Layout hook tracking (required)

const LAYOUT_HOOK_VIEWPORTS = new Set<string>();

// Inside layout test after successful capture:
LAYOUT_HOOK_VIEWPORTS.add(vp.name);

appendResults() contract

1. If QA_RESULTS.length === 0 → return (no write). 2. Append ## Test Run — {ISO} with all grouped rows for this run. 3. AI Review Hooks table is mandatory when LAYOUT_HOOK_VIEWPORTS.size > 0:

lines.push('### AI Review Hooks');
lines.push('| Viewport | Hook | Status |');
for (const vpName of LAYOUT_HOOK_VIEWPORTS) {
  const alreadyReviewed = existingContent.includes(`## AI Visual Review — ${vpName}`);
  const hookStatus = alreadyReviewed ? 'ai-review-completed' : 'pending-ai-review';
  lines.push(`| ${vpName} | QA_AI_ANALYSIS_READY | ${hookStatus} |`);
}

4. Never emit an empty AI Review Hooks table when layout ran. 5. Append-only — never truncate test-result.md.

Monitor completion status update

After the monitor appends all required AI review sections for a viewport, it must update the processed hook row status from pending-ai-review to ai-review-completed.

This is the only allowed in-place edit to test-result.md. The monitor must not rewrite result rows, prior review sections, screenshots, specs, or site source. If multiple pending hook rows exist, update only the rows whose viewport screenshots were actually reviewed.

stdout hooks (layout test)

Always log both:

console.log(`[QA_SCREENSHOTS_READY] test-results/${PAGE_SLUG}/screenshots/ (...)`);
console.log(`[QA_AI_ANALYSIS_READY] ${JSON.stringify({ pageSlug, viewport, screenshotDir, slices, resultFile, reviewStatus: 'pending-ai-review', contentZone: { headerHeight, bottomBarHeight } })}`);

Monitor agent watches file hooks (pending-ai-review in md), updates processed hooks to ai-review-completed, and stdout is optional.

qa-run-config.json

• Omit removed categories from tests: forms, dynamic widgets, page rendering/framework integrity, and accessibility smoke checks.
• Devices default false.

Spec Self-Check (before reporting completion)

• [ ] test.describe.configure({ mode: 'serial' }) at file top
• [ ] Each enabled viewport/device has its own test.describe(vp.name, ...) block containing that device's tests
• [ ] LAYOUT_HOOK_VIEWPORTS Set + populated in layout test
• [ ] appendResults writes AI hooks from LAYOUT_HOOK_VIEWPORTS (never empty when layout ran)
• [ ] 6 grouped QA tests inside each device block
• [ ] No forms, dynamic widget, page rendering/framework integrity, or accessibility smoke tests
• [ ] ensureInViewport before every link, button, media, and section check
• [ ] Section test: highlightSectionBand + clearSectionBand + overlay SECTION n/N — label
• [ ] classList.contains exclusion; content-root early exit; no className.includes
• [ ] Links/CTAs collected as plain objects; cap 40 links
• [ ] Media selectors include Elementor paths
• [ ] Layout: content-zone clips, console hooks, warning row
• [ ] afterAll → appendResults only
• [ ] User docs mention --workers=1

Test Matrix (v2) — 6 Grouped Tests

Generate exactly these 6 grouped QA tests inside each enabled device/viewport test.describe(vp.name, ...) block. Do not generate forms, dynamic widgets, page rendering/framework integrity, or accessibility smoke tests.

Per-item requirements (all tests)

• Device grouping is mandatory: desktop tests live under the desktop describe block, tablet tests under tablet, and mobile tests under mobile. Do not rely on test-name prefixes as the only grouping.
• await page.goto(PAGE_URL) before first overlay.
• `await ensureInViewport(target)` before highlight, click, screenshot of that target, or section scroll position.
• showQaOverlay with progress label (LINK 3/22, SECTION 5/14, etc.).
• Crash safety: resultsPushed + top-level try/catch.
• Fail grouped test at end if any item fail; continue other items when safe.

Section test (test 4) — mandatory visuals

For each section:

1. ensureInViewport using section top coordinate (scroll top - 80px padding). 2. highlightSectionBand(page, top, height, label) — green dashed band + label on page. 3. showQaOverlay(page, 'SECTION n/N — {label}', 'running'). 4. Record pass/fail for populated content. 5. clearSectionBand(page) before next section.

Layout test (test 6) — mandatory hooks

1. detectStickyOverlays → showContentAreaHighlight (2s) → remove bands → captureLayoutSlices. 2. console.log('[QA_SCREENSHOTS_READY] …'). 3. console.log('[QA_AI_ANALYSIS_READY] ' + JSON.stringify({…})). 4. LAYOUT_HOOK_VIEWPORTS.add(vp.name). 5. Warning result row; do not fail after successful capture.

Link test (test 2)

• Collect { href, text, top } in one page.evaluate.
• For each link: ensureInViewport at top → highlight → navigate/verify → return.

Media test (test 5)

• Broad selectors: main img, [role="main"] img, .elementor-section img, .elementor-widget-image img, section img, .wp-block-image img (exclude header/footer via isInsideExcludedRegion).
• Do not rely on main img alone on Elementor pages.

Removed tests

Do not generate these categories in v2:

• dynamic widgets operate correctly
• page rendering and framework integrity
• accessibility smoke checks
• all forms and inputs render and validate safely

AI Visual Review (v2)

Delegated to `qa-visual-review-monitor` monitor agent (agents/qa-visual-review-monitor.toml).

Parent agent after spec generation

1. Spawn monitor once per workspace (reuse if active). 2. Do not claim review is done until ## AI Visual Review — [viewport] exists in test-result.md. 3. Spawn with a strict spelling instruction: the monitor must do both a line pass and a word/token pass, must not rely on prior spelling sections, and must append a supplemental spelling audit if a review already exists but the user requests a stricter recheck. 4. If the user reports that spelling mistakes were missed, treat the earlier review as incomplete and run supplemental mode even when there are no pending hook rows left.

Reviewer scope

Main content only. Categories: overflow-and-bleed, element-overlap, typography, layout-alignment, images-media, and spelling.

Spelling protocol

• Every slice in order; line-by-line visible text in main content.
• Then perform a second word/token pass on each slice.
• Report all confirmed typos (not just first), including missing letters, extra letters, transpositions, missing spaces, merged words, odd in-word capitalization, and malformed common phrases.
• Cover hero copy, section intros, small cards, outcome cards, labels/pills, CTA text, repeated boundary text, and low-contrast body copy. These areas are where previous review passes most often miss small typos.
• Compare repeated boundary text across adjacent slices; deduplicate findings while listing all slices where an issue is visible.
• Compare adjacent slices at boundaries before reporting clip/overlap.
• Allow brand/product/technology names unless clearly wrong.

Sections to append (bottom of test-result.md)

1. ## AI Visual Review — [viewport] 2. ## Spelling Check — [viewport] 3. ## UI Suggestions — [viewport] 4. AI Review Completion Note

After appending those sections, update the processed hook row status from pending-ai-review to ai-review-completed. This hook status update is the only allowed in-place edit. Do not rewrite prior result rows or review sections. Do not create extra markdown files.

Strict monitor spawn text

When spawning qa-visual-review-monitor, include this text:

Perform a strict spelling audit. Do not rely on any previous Spelling Check section. Read every screenshot slice in order, then do a second word/token pass for small copy, cards, pills, buttons, repeated boundary text, missing spaces, merged words, odd capitalization, transpositions, and near-word errors. Report every confirmed typo with all visible slice names. If an AI review already exists for the viewport, append Supplemental Spelling Audit sections at the bottom. After appending review sections for a viewport, update that viewport's processed hook row from `pending-ai-review` to `ai-review-completed`; do not rewrite any other hook rows or prior review sections.

Strict supplemental re-audit spawn text

Use this exact shape when the user reports that a prior spelling review missed issues:

Use the qa-visual-review-monitor monitor agent defined in agents/qa-visual-review-monitor.toml. A previous AI review exists, but the user reports it missed spelling mistakes. Perform a strict supplemental spelling audit, not a normal first-pass review.

Workspace: [absolute workspace path]
Result file: test-results/[page-slug]/test-result.md
Screenshots: test-results/[page-slug]/screenshots/[viewport]_slice_001.png through [viewport]_slice_NNN.png

Required behavior:
- Do not edit existing hook rows or previous review sections except to update the processed hook status from `pending-ai-review` to `ai-review-completed` after appending the supplemental sections.
- Append only at the bottom of test-result.md.
- Read every [viewport] screenshot slice in order.
- Do a line pass and then a word/token pass.
- Look for hero copy, small card/body copy, labels, pills, buttons, repeated boundary text, missing spaces, merged words, odd capitalization, transpositions, and near-word errors.
- Report every confirmed typo with all visible slice names.
- If uncertain about product/domain terminology, put it in Supplemental UI Suggestions as low confidence, not as a confirmed typo.
- Append `## Supplemental Spelling Audit — [viewport]`, `## Supplemental UI Suggestions — [viewport]`, and `Supplemental AI Review Completion Note`.

Spelling tables must use this shape for consistent results:

| Slice | Text | Issue | Suggested correction | Confidence |
| --- | --- | --- | --- | --- |

False positives

• Intentional sticky/fixed/floating UI
• Slice boundary cutoffs
• Header/footer content