Screenshot Analyze Verification

Purpose

Use this skill whenever screenshots are presented as proof of UI correctness. This is a strict, fail-fast workflow.

If any hard gate fails, status is NOT VERIFIED.

Required Inputs (must be explicit)

Do not start validation until all inputs are known:

• Requested app and page/screen.
• Scenario name/state (for example Training Plan Card, Top Toolbar Button).
• Required simulator/OS coverage.
• Required theme coverage (light and/or dark mode).
• Required visible elements.
• Required hidden or de-emphasized elements.
• Interaction expectation (tap target works, bubble tap ignored, outside tap dismisses).

If inputs are incomplete, ask for missing details before approving.

Hard Gates (non-negotiable)

Gate 1: Correct App and Correct Page

Fail if capture is from wrong app, wrong screen, wrong route, or wrong scenario.

Required checks:

• Landmark text and hierarchy match expected screen (title, subtitle, scenario label).
• Navigation/chrome match expected route.
• Capture is not from onboarding/other flow when home/lab was requested.
• Scenario-specific label matches requested scenario.

Failure label:

• NOT VERIFIED: wrong app/page/sim capture

Gate 2: Required Elements Present and Complete

Fail if any required element is missing, cropped, or partially outside valid bounds.

Required checks:

• Target element exists and is fully visible.
• Bubble exists, text is complete, arrow/tail is visible.
• Required control(s) for the scenario are present.

Gate 3: Hidden/De-emphasized Elements Are Actually Suppressed

Fail if non-target UI remains too prominent when spotlight state is active.

Required checks:

• Dimming/blur overlay covers all non-highlight regions uniformly.
• Highlight hole is tightly scoped to the target (does not include unrelated UI).
• Elements required to be hidden/de-emphasized are clearly subdued.
• Persistent chrome elements (for example bottom input bars, tab bars, sticky headers) are also subdued unless they are the target.

Gate 4: Text Legibility and Contrast

Fail if any critical text is hard to read in required mode(s).

Required checks:

• Primary instructional text is readable at first glance.
• Secondary/supporting text remains readable when meant to be shown.
• Contrast is sufficient over backgrounds/material effects in light and dark mode.
• No text blending into bright highlights or dark blur.

Practical threshold guidance:

• Aim at WCAG-like body-text contrast around 4.5:1 equivalent for critical content.
• If visual inspection is borderline, treat as fail.

Gate 5: Layout Integrity and Geometry

Fail on any geometry defect that harms clarity.

Required checks:

• No overlapping bubbles or overlap between bubble and critical UI text.
• Long text wraps inside bubble bounds; no text overflow outside shape.
• Bubble padding is adequate and consistent.
• Arrow/tail is attached and not detached/floating.
• Arrow points to actual target location (not centered incorrectly after clamping).
• Bubble and tail are not clipped by safe areas, notch, status bar, or home indicator.

Exact Validation Checklist

Mark every row PASS or FAIL. Any FAIL => NOT VERIFIED.

1. Context fidelity

• Correct app?
• Correct page/route?
• Correct scenario/state text?
• Correct simulator + OS label for file?

2. Required element presence

• Target element present?
• Bubble present?
• Arrow present?
• All mandatory controls present?

3. Spotlight/hide behavior

• Non-target dimming active and even?
• Highlight aperture constrained to target frame?
• Elements that should be subdued are subdued (including persistent chrome)?
• Tap semantics respected by visual state (bubble informational, target actionable)?

4. Copy and readability

• Text fully visible and not truncated incorrectly?
• Contrast acceptable in all required modes?
• No tiny unreadable labels?

5. Spacing and containment

• Bubble text-to-edge padding adequate (target: ~12-16pt horizontal, ~10-14pt vertical visual equivalent)?
• Long tokens wrap/break without spilling?
• No overlap with neighboring bubbles/components?

6. Arrow correctness

• Tail remains attached at all offsets?
• Tail tip lands on or near intended target anchor?
• Right-side targets use right-biased arrow position when expected?

7. Cross-mode parity

• All requested OS versions captured?
• At least one dark-mode screenshot per required simulator when dark mode is required?
• No mode-specific regressions in contrast, placement, clipping?

Common Regression Patterns (Generic)

Treat these as mandatory anti-regression checks. Convert each observed pattern into a finding.

• INT-01 Wrong capture context: screenshot is from a different app, route, or scenario than requested.
• INT-02 Stale build capture: screenshot was taken from an older binary, not the latest build/reinstall.
• INT-03 Composition overlap: hints/bubbles or critical UI overlap and reduce readability.
• INT-04 Detached pointer/tail: callout pointer visually disconnects from bubble body.
• INT-05 Theme readability regression: light/dark mode causes text contrast or legibility failures.
• INT-06 Safe-area clipping: bubble/pointer clips at notch, status bar, or home-indicator regions.
• INT-07 Pointer mis-targeting after clamping: bubble is clamped in bounds but pointer no longer points at target.
• INT-08 Highlight aperture overreach: spotlight reveals unrelated content outside target scope.
• INT-09 Suppression leak: non-target persistent UI remains too prominent during spotlight.
• INT-10 Visual ambiguity: arrangement appears broken/accidental rather than intentional hierarchy.

Severity guidance:

• INT-01/02/07/09 are P1.
• INT-03/04/06/08/10 are P1 unless clearly cosmetic and non-blocking.
• INT-05 is at least P2, and P1 when instructional text is difficult to read.

Apple UI/UX Practice Layer

Apply Apple-oriented review criteria (from apple-hig-designer principles):

• Clarity: hierarchy obvious, text instantly legible.
• Deference: overlay supports the task and does not visually compete.
• Depth: layering and material effects communicate focus, not noise.
• Accessibility baseline:
  • sufficient color contrast in light/dark,
  • readable sizes,
  • critical meaning not conveyed by low-contrast decoration alone.

If these principles are violated in a way that affects task completion, fail validation.

Capture Protocol (before analysis)

When screenshots are newly generated, enforce this protocol:

1. Rebuild and reinstall latest binary on each required simulator.
2. Launch exact scenario/state to be validated.
3. Capture deterministic filenames:
   • <platform>-<os>-<scenario>-light.png
   • <platform>-<os>-<scenario>-dark.png
4. Verify each file visually matches intended app/page before reporting.

If protocol is not followed, set status to NOT VERIFIED.

Required Output Format

Always respond in this structure:

1. Verification Status: VERIFIED or NOT VERIFIED
2. Hard Gate Results:
   • Gate 1: PASS/FAIL
   • Gate 2: PASS/FAIL
   • Gate 3: PASS/FAIL
   • Gate 4: PASS/FAIL
   • Gate 5: PASS/FAIL
3. Findings:
   • Sorted by severity (P1, P2, P3)
   • Include screenshot path(s)
   • Include exact defect and impact
4. Required Fixes Before Approval
5. Residual Risks (only if status is VERIFIED with caveats)

Approval rule:

• Never return VERIFIED if any hard gate failed.