Reference-Driven Frontend Debugging

Use this skill when a frontend task is anchored to a real webpage reference and the goal is not just "implement something similar", but to get the actual runtime behavior closer to that reference.

The central rule is simple: when the user provides a reference webpage URL, do not rely on static code inspection alone. Open the reference page and the local project at the same time with #io.github.chromedevtools/chrome-devtools-mcp, compare them live, and debug the interaction in the browser until the real behavior matches the intended outcome closely enough.

What This Skill Is For

Use this skill for tasks like:

• Matching a page layout, spacing, typography, icon sizing, or visual rhythm against a live site
• Reproducing interaction details such as drag-and-drop, hover states, drop highlights, overlays, breadcrumbs, context menus, double-click behavior, or panel transitions
• Fixing cases where the implementation "looks right in code" but feels wrong in the browser
• Investigating second-round feedback like "效果不符合预期", "交互不对", "鼠标位置偏了", "拖不到目标位置", "和参考站不一样"

Required Working Mode

When this skill triggers, ALWAYS do the following:

1. Open the reference webpage in one browser page.
2. Open the local project in a separate browser page.
3. Keep both pages available throughout the task instead of replacing one with the other.
4. Reproduce the target interaction in the local page, not just the reference page.
5. Use Chrome DevTools MCP browser tooling to inspect real runtime state before and after edits.

If the reference site requires authentication and an authenticated page already exists, reuse that page instead of trying to rebuild the login flow unless the task requires it.

Workflow

1. Establish the comparison baseline

• Open the reference URL and confirm the exact screen or state the user wants to copy.
• Open the local project page that should match it.
• Capture a page snapshot or screenshot for both when visual comparison matters.
• Identify the concrete target, not just the broad page: for example, breadcrumb spacing, drag card position, left tree hover feedback, or drop target behavior.

Do not start editing until the target behavior is expressed as specific observable runtime facts.

2. Reproduce the real interaction

Run the actual interaction in the local project before changing code.

Examples:

• Drag a file row onto a folder row
• Drag an item into the left directory tree
• Drag an item onto a breadcrumb segment to move up one level
• Double-click a folder row to enter it
• Hover the target area and inspect whether highlight state appears

The point is to observe what the browser is really doing, not what the code suggests it should do.

3. Use browser evidence to locate the mismatch

When the behavior is wrong, inspect runtime evidence with #io.github.chromedevtools/chrome-devtools-mcp. Prefer direct evidence like:

• Element bounding boxes
• Overlay position versus pointer position
• elementsFromPoint(...) hit stacks near the pointer
• Active drop target classes or highlight state
• Request payloads for mutations triggered by the interaction
• The final rendered state after drop, click, or navigation

This is especially important for interaction bugs where static reasoning is often misleading.

Debugging Checklist By Interaction Type

Drag-and-drop

Always verify all of these in the browser:

• The drag overlay appears where the pointer suggests it should appear
• The intended drop target highlights while hovering
• The drop target is actually the one receiving the event
• The move or mutation request is really sent with the expected source and destination paths
• The UI updates after the move, not just the accessibility status text

For drag-and-drop, do not stop after seeing "dropped". Confirm what it was dropped over and whether data actually changed.

Navigation handoff

For breadcrumbs, tree nodes, or row double-click navigation, verify:

• The clickable or droppable area is large enough to use comfortably
• The current path or breadcrumb really changes
• The resulting list content matches the new location

Visual alignment

For spacing, chip layout, icon size, or header rhythm, compare both pages directly. If the reference page uses larger interaction hit areas than the local implementation, copy the interactive footprint, not just the text content.

Editing Loop

After each meaningful code change:

1. Reload the local page.
2. Re-run the specific interaction that was previously wrong.
3. Re-check the same runtime evidence.
4. Compare again against the reference page.

Do not assume a code fix worked just because it compiles or the DOM structure changed.

Preferred Tool Usage

Prefer #io.github.chromedevtools/chrome-devtools-mcp browser tools for this workflow:

• Open a dedicated page for the reference site
• Open a dedicated page for the local project
• Read page snapshots to discover current UI structure
• Capture screenshots when visual differences matter
• Use page evaluation helpers to inspect bounding rects, hit-testing, request details, and live DOM state

Use terminal and code search tools only to support the browser findings, not to replace them.

Output Expectations

When finishing the task, the result should include:

• The code change that addressed the runtime mismatch
• A short explanation of what the actual root cause was in browser terms
• Evidence that the interaction was re-tested in the live page
• The package or project validation command result if code was modified

Guardrails

• Do not treat a reference URL as a purely visual mood board. Treat it as a runtime specification.
• Do not stop at "the code now looks reasonable". The browser must confirm it.
• Do not rely on one screenshot for interaction-heavy tasks. Execute the interaction.
• Do not replace the reference page with the local page during debugging. Keep both available for comparison.
• If the issue is about runtime feel, hit-testing, hover, drag, overlay position, or gesture behavior, prefer browser evidence over assumptions from component code.

Example Triggers

• "请参考 https://drive.google.com/drive/my-drive 调整 Explorer 的交互"
• "我给你一个参考网页，按这个实现前端效果"
• "效果不符合预期，请用 Chrome DevTools MCP 调试"
• "拖拽已经实现，但和参考网页的实际交互还有偏差"
• "请把本项目页面和参考站一起打开，对照修复前端行为"