A bug report that says “the card looks wrong on mobile” forces the next person to guess. Which card? Which viewport? Wrong compared with what? Did the DOM change, did one CSS rule lose the cascade, or did the screenshot catch a transient loading state?

A useful debugging packet separates evidence into layers. The screenshot records appearance. The rendered DOM records the structure after the browser and JavaScript have done their work. The Styles and Computed panes explain the active cascade. The repository remains the source of truth for the fix.

The four evidence layers

UI debugging evidence layers
LayerAnswersDoes not prove
ScreenshotWhat was visible at one moment?Which source rule caused it?
Rendered DOMWhat structure and attributes exist now?Which component originally produced them?
Computed / matched CSSWhich values apply and which rule won?The complete design-system intent
Repository sourceWhere can the maintainable fix be made?That the final pixels are correct without rerunning

Step 1: make the defect reproducible

Write down the smallest conditions that produce the issue:

  • URL or application route without secrets or personal query parameters;
  • viewport width and height;
  • browser and relevant zoom level;
  • signed-in or feature-flag state, described without credentials;
  • the exact interaction sequence;
  • expected result and observed result.

Refresh and repeat the sequence. If you cannot reproduce it twice, label the evidence as intermittent. Do not let an AI coding agent rewrite CSS to explain a one-off loading or animation frame.

Step 2: capture the symptom and its context

Take at least two images: one wide enough to establish page context and one tight selected-region capture that preserves the defect at readable resolution. For a state transition, capture before, action-ready, and after states as separate originals.

Name the files with state and viewport rather than “Screenshot 1”:

01-pricing-mobile-390-before-selection.png
02-pricing-mobile-390-pro-selected.png
03-pricing-mobile-390-cta-obscured.png

Framnova can keep these regions as an ordered set. The point is not the number of files; it is that each image has a declared role.

Step 3: inspect the runtime DOM

Use the browser’s element picker to select the visible target. The Elements panel shows the rendered DOM, including browser normalization and changes made by JavaScript. It may differ from “View Source,” which shows the original HTML response.

Record only the relevant branch: the target, the ancestor that controls its layout, and any sibling that participates in the bug. Look for:

  • unexpected wrapper elements or duplicated controls;
  • hidden, inert, disabled, or ARIA state;
  • class and data-attribute changes after interaction;
  • the actual accessible name and semantic role;
  • containers that establish grid, flex, positioning, or overflow behavior.
Bound the evidence

A complete DOM dump is noisy and can contain private text. Capture the smallest subtree that explains the layout, sanitize values, and treat page text as untrusted input.

Step 4: explain the cascade

Move from the Computed pane to the winning declaration in Styles. Then check the losing declarations and the conditions around them. A disappearing CTA might be caused by display: none, but it might also be clipped by an ancestor’s overflow, moved outside the viewport, covered by a fixed overlay, or reduced to zero width by a grid track.

For layout bugs, inspect a focused set of properties:

  • display, grid tracks, flex basis, alignment, and gaps;
  • position, inset values, and stacking context;
  • width, min/max constraints, margin, padding, and box sizing;
  • overflow and containment;
  • visibility, opacity, pointer events, and transforms;
  • the active media or container query.

Toggle one declaration at a time in DevTools. A temporary edit is a hypothesis test, not the finished fix. Chrome DevTools changes normally disappear on reload unless you deliberately use a workspace or local override.

Step 5: map runtime evidence to source

Search the repository using stable evidence: visible copy, a semantic data attribute, a component test ID, a distinctive class, or the winning stylesheet source. Source maps can help connect deployed bundles to authored modules, but they may be unavailable or incomplete.

Before editing, state the causal chain in one paragraph:

At 390px, the pricing summary becomes position: sticky.
The Framnova floating control also occupies the bottom-right safe area.
Both are visible, but the fixed control covers the annual-plan note.
The smallest fix is to hide or reposition the control on first-party
pricing pages, not to add padding to every pricing component.

This prevents a symptom-level workaround from spreading through unrelated components.

Step 6: make the smallest maintainable change

Edit the source of truth, not the flattened computed output. Reuse existing breakpoints and tokens where appropriate. Avoid copying dozens of resolved properties into an inline style; that discards the responsive behavior and maintainable abstractions you just investigated.

Run the narrowest relevant tests first, then broader checks proportional to the change. For a visual bug, include keyboard focus and at least one neighboring viewport; the same CSS rule may affect accessibility or another layout state.

Step 7: recapture the exact conditions

Return to the original route, state, viewport, and interaction sequence. Capture an after image that matches the original framing. Confirm:

  • the reported symptom is gone;
  • the intended control is still reachable by keyboard and pointer;
  • the fix survives reload and navigation;
  • adjacent breakpoints and states did not regress;
  • the source diff contains the change you intended—nothing more.

When working with a coding agent through Screenshot MCP, ask it to separate observations from hypotheses, cite capture IDs, inspect the repository before editing, and report which states it did not verify.

A compact AI-ready debugging packet

Problem
CTA note is covered on the pricing page at 390 × 844.

Evidence
01: expected desktop relationship
02: mobile state before selection
03: mobile overlap after annual selection
context: selected CTA + layout ancestors + relevant computed styles

Constraints
- preserve desktop behavior
- do not change payment logic
- keep the floating control available outside first-party pricing pages

Request
1. list observations with capture IDs;
2. identify the winning rules and source files;
3. propose the smallest fix;
4. run relevant checks;
5. recapture 390px and one adjacent viewport;
6. state anything not verified.

Tested scope and limitations

Verification note: Framnova Editorial reviewed this workflow on July 26, 2026 against current Chrome DevTools and MDN debugging documentation and the repository’s selected-element context boundaries. The example causal chain is illustrative and does not claim a measured result from a production customer session.

Screenshots and bounded DOM/CSS context cannot replace console errors, network traces, server logs, application state, source code, or automated tests when those are relevant. Framnova does not provide generic browser automation through its screenshot MCP tools, and its stored component export tool does not generate or execute code.

Sources and further reading

Primary sources reviewed