frontend-devtools-skill

Frontend Devtools Skill

Use this skill when a visual or layout problem is easier to solve with browser inspection than by reading source alone, or when you need to build a website that should look intentional and work well across screen sizes. The CLI/tool name is frontend-devtools-skill.

This skill is for:

• Building or refining a full website, landing page, or marketing page
• Researching an existing website the user wants to reference or be inspired by
• CSS cascade questions: "why is this style winning?"
• Box model and spacing issues
• Flex/grid parent-context inspection
• Overflow and clipping diagnosis
• Console and network checks tied to a real page
• Responsive debugging when you need a specific viewport or browser state
• Visual diff checks against a reference image

Do not use this skill when a simple source edit is enough and browser state is irrelevant.

Website-Building Default

When the user asks for a website, landing page, homepage, or redesign:

• Build the page, do not stop at suggestions unless the user explicitly asked for ideas only.
• Decide what the website is trying to communicate before choosing styles. The visual system should match the idea of the site.
• For new website design work, read references/design-for-startups-garry-tan.md before composing the page.
• For implementation quality, read references/frontend-engineering-principles.md before building a fresh marketing site, UI system, or major redesign.
• Treat responsive design as required, not optional.
• Check the page at desktop and mobile widths before closing out.
• Favor strong visual direction over bland defaults.
• Optimize for both appearance and behavior: spacing, hierarchy, navigation, interaction states, overflow, and real content fit all matter.
• Use the frontend-devtools-skill CLI during the build, not only after something breaks.
• Treat poor contrast, hard-to-read text, weak button clarity, and washed-out sections as real bugs.

Minimum quality bar:

• Desktop layout works cleanly at common laptop widths.
• Mobile layout works cleanly around phone widths.
• No obvious clipped text, horizontal overflow, broken buttons, or missing assets.
• Typography, spacing, and color choices feel intentional rather than boilerplate.
• Primary text, muted text, buttons, tags, and overlays remain readable against their backgrounds.

Inspiration Research Default

If the user provides an existing website URL for inspiration:

• Research it before designing.
• Open the live site and inspect it directly, do not rely on memory or vague style imitation.
• Identify what is worth borrowing: hierarchy, pacing, type scale, grid behavior, card treatment, navigation rhythm, color structure, or motion tone.
• Inspect the live DOM and computed CSS on key sections when possible.
• Read the page code or source assets when accessible and useful, especially for layout structure and component patterns.
• Do not clone blindly. Extract principles, then adapt them to the user's actual goal and content.

When reporting what you learned from an inspiration site, mention:

• the site or section you inspected
• the specific design ideas you are carrying over
• what you intentionally changed for the user's context

Workflow

1. Build or serve the target page first.
2. For quick checks, use --url and let frontend-devtools-skill launch its own headless browser.
3. For responsive or stateful debugging, launch a clean attachable browser first:

frontend-devtools-skill browser --port 9222 --url http://localhost:3000

This uses a temporary profile plus safe flags that avoid macOS keychain password prompts.

1. Reuse that browser with --connect http://127.0.0.1:9222.
2. If you are building a page, inspect early instead of waiting for a bug report.
3. Inspect the relevant element before editing CSS.
4. After changes, rerun the same command to confirm the result.
5. Before closing out a website task, verify both desktop and mobile.

Command Guide

Inspect one element

Use when you need computed styles, cascade order, box model, or parent layout context.

frontend-devtools-skill inspect ".hero-card" --url http://localhost:3000 --pretty
frontend-devtools-skill inspect ".hero-card" --connect http://127.0.0.1:9222 --pretty

Look at:

• computedStyles for the current truth
• cssRules to see where values came from
• boxModel for real spacing
• parentContext for grid/flex constraints

Diagnose layout problems

Use when the issue is overflow, clipping, fixed sizing, or ancestor constraints.

frontend-devtools-skill diagnose ".overflowing-panel" --url http://localhost:3000 --problem overflow --pretty
frontend-devtools-skill diagnose ".overflowing-panel" --connect http://127.0.0.1:9222 --problem overflow --pretty

Treat rootCause as a lead, not a final verdict. Cross-check it against the computed styles and the page itself.

Snapshot the full layout tree

Use when the bug is structural or you need to understand the broader DOM/layout shape.

frontend-devtools-skill snapshot --url http://localhost:3000 --selector ".main" --pretty
frontend-devtools-skill snapshot --connect http://127.0.0.1:9222 --selector ".main" --pretty

Console and network

Use these after the page is already working visually, or when browser errors may explain the visual bug.

frontend-devtools-skill console --url http://localhost:3000 --level warning --pretty
frontend-devtools-skill console --connect http://127.0.0.1:9222 --pretty

frontend-devtools-skill network --url http://localhost:3000 --failed-only --pretty
frontend-devtools-skill network --connect http://127.0.0.1:9222 --failed-only --pretty

These commands navigate or reload the page. Do not run them in parallel with inspect or diagnose against the same attached tab.

Visual diff

Use only when you already have a reference image and want a fast mismatch signal.

frontend-devtools-skill diff ./reference.png --url http://localhost:3000 --selector ".hero" --threshold 0.1 --pretty
frontend-devtools-skill diff ./reference.png --connect http://127.0.0.1:9222 --selector ".hero" --threshold 0.1 --pretty

• threshold is allowed mismatch percentage
• pixelThreshold is per-pixel sensitivity

Practical Heuristics

• If the task is "build a website", assume the user wants a finished page with real styling, not a wireframe.
• Start by naming the page idea in one short sentence before building: what it should feel like and what it should persuade the user to do.
• Treat the interface like a polite conversation and a well-hosted party: welcome the user, orient them quickly, and make the next step obvious.
• Start with inspect before editing CSS blindly.
• If widths or heights look suspicious, compare the element to parentContext.
• If a responsive issue only appears at a specific size, use frontend-devtools-skill browser and attach with --connect.
• If connect fails, relaunch through frontend-devtools-skill browser instead of attaching to a personal Chrome profile.
• When outputs conflict with what you see, trust the live page first and rerun the command after the page settles.
• Use console and network once before finishing a real website task.
• Prefer a cohesive visual system: one clear type direction, one clear color story, consistent radii, and deliberate spacing.
• Use direct command language for CTAs and empty states. Avoid vague, passive homepage copy.
• Build from reusable patterns and stable layout primitives instead of bespoke one-off sections.
• If a layout only works on one breakpoint, it is not done.
• Remove ornament that does not carry meaning. If a decorative layer can disappear without hurting comprehension, remove it.
• If text is hard to read at a glance, fix the contrast or background treatment before doing anything decorative.
• Use contrast deliberately, then run the squint test to confirm the most important action is visually dominant.
• Group related elements tightly, separate unrelated ones clearly, and use grid before ad hoc spacing.
• Treat accessibility and performance as first-order UI requirements, not cleanup tasks after visual polish.
• Check dark overlays, gradient sections, badges, and secondary text manually; these are common contrast failure points.
• If a large empty panel, washed-out card, or oversized surface reads like accidental browser chrome or a placeholder, treat it as a design bug and either fill it with meaningful composition or remove it.

Example Debug Loop

1. Open the page at the failing viewport with frontend-devtools-skill browser.
2. Run inspect on the broken element.
3. Run diagnose if the problem looks like clipping or layout containment.
4. Patch the CSS.
5. Rerun inspect on the same selector.
6. Run console and network once before closing out.

Website Finish Checklist

Before you say a website is done:

• Confirm the page idea is visually clear, not just decorative.
• Review the page at desktop width.
• Review the page at mobile width.
• Run inspect or diagnose on any suspicious layout area instead of assuming.
• Check color contrast and readability in the hero, buttons, cards, tags, footer, and any gradient or image-backed sections.
• Check for large empty surfaces that feel like accidental UI chrome, dead panels, or unfinished placeholders.
• Run console and network.
• Make sure the final result is both attractive and usable.

Output Expectations

When using this skill, include:

• The exact command you ran
• The selector or page you inspected
• The one or two fields from the JSON that mattered
• The edit you made because of that output

Avoid dumping the full JSON unless the user asked for it.