Design Research

Capture a flow with agent-browser and place the screenshots into a Figma refs section, one labelled row per source, matching whatever row already exists. Optionally layer observations next to the screens (review agents) and a comparison across sources. Ends by handing off to research-synthesis.

Sources can be public websites, logged-in web apps (a WordPress admin is one kind of logged-in app here), or apps running locally. This skill never modifies the target site: no CLI, no plugin or data changes. WordPress-specific setup (WP-CLI, temp users, plugin hygiene) lives in the separate wp-plugin-research skill, which calls back into this one for capture and placement.

REQUIRED SUB-SKILL: load figma:figma-use before any use_figma call.

Supporting files: capture.md (login, capture, Figma placement recipe), review-layer.md (review brief, agents, placing observations, gallery, comparison). shared/common-steps.md holds permissions, shell rules, capture strategy, gallery and troubleshooting.

Quick Reference

BEFORE YOU START: Create Tasks

Use TaskCreate for each step. Mark in_progress when starting and completed when done.

1. "Step 0: Permissions and prerequisites"
2. "Step 1: Gather input"
3. "Step 2: Read target section"
4. "Step 3: Login per source"
5. "Step 4: Capture and verify"
6. "Step 5: Place rows in Figma"
7. "Step 6: Review layer (if chosen)"
8. "Step 7: Comparison (if chosen)"
9. "Step 8: Verify, report, hand off"

Step 0: Permissions and Prerequisites

Read shared/common-steps.md, "Permissions" and "No Shell Variables in Bash Commands". Recommend auto mode before the command-heavy steps.

Figma is the default output, so the Figma MCP is required. If the user only wants PNGs on disk, stop after Step 4 and say so.

Step 1: Gather Input (Single Interaction)

One AskUserQuestion. The user answers everything and walks away.

Sources. URLs, or a discovery query ("booking apps with an admin calendar") resolved with WebSearch into a numbered list the user picks from. For each source: is it public, needs a login (credentials, or the user will log in when asked), or runs locally?

Flow. Which screens, in order. Options: "homepage plus key pages", "this admin flow: <steps>", "let me explore and propose a list" (navigate, build the list, show it, then capture).

Refs section. The Figma URL of the section to place rows in, or the page to create one on. A node-id=A-B in the URL is node A:B.

Layers. Multi-select:

• Refs only. Screens on the canvas, nothing else. Default.
• Observations next to the screens. A review agent reads the screens (marketing lens for public sites, app-UX lens for admin UIs) and the observations are placed on the canvas beside each screen. Ask for the lens (General UX, First-time experience, Marketing effectiveness, Conversion flow, Upsell and monetization, or a sentence of their own) and the depth (Light, or Impact and Opportunity scores).
• HTML gallery. The annotated gallery as well as, or instead of, canvas notes.
• Comparison. Only with 2+ sources: a comparator agent rates sources across dimensions with a verdict.

Print a plan summary (sources, flow, section, layers, estimated screens) and start. No further gates before writing to Figma; this flow is for unattended runs. The final message carries a section screenshot so the user can check and undo.

Step 2: Read the Target Section

Follow capture.md, "Layout rule". If the parent section already holds a row, read it and copy its numbers (tile size, gap, padding, label font, fill). If empty, use the defaults. Name the page and the row matched in the final message.

Step 3: Login per Source

Follow capture.md, "Login". Generic form login only: open the login URL, fill the fields found with snapshot -i, submit, verify the landing page. SSO, 2FA, captcha, or a magic link: hand back to the user with one AskUserQuestion ("Log in in the agent-browser window, then tell me to continue"). Re-login before each source; sessions expire.

Step 4: Capture and Verify

Follow capture.md, "Capture". One folder per source screenshots/<source-slug>/, files NN-description.png in flow order, chunked -p1, -p2 for pages taller than one viewport. Read every PNG after capture. Drop near-duplicates. Keep a journey note per screen (one to three factual sentences) even in refs-only mode; the review layer and research-synthesis both use them.

Step 5: Place Rows in Figma

Follow capture.md, "Place rows in Figma". One sub-section per source inside the parent, tiles as rectangles with IMAGE fills, labels above tiles from the filenames, uploaded with upload_assets in filename order. Grow the parent. Verify the IMAGE fill count equals the tile count before moving to the next source.

Step 6: Review Layer (optional)

Follow review-layer.md. Write a review brief per source, dispatch agents/marketing-reviewer.md (public sites) or agents/ux-reviewer.md (apps and admin UIs) as general-purpose subagents, validate the manifest counts, then place the observations:

• On the canvas (default when chosen): one note per screen beside its tile, using a design-system note component if the user has one or the default note template from design-annotations. Each observation is one line with its type (positive, observation, critical) and, for Impact and Opportunity depth, its scores.
• HTML gallery: shared/common-steps.md, "Generate HTML Gallery" and "Local Server & Gallery Verification". Ask for approval before importing the gallery to Figma.

Step 7: Comparison (optional)

Only with 2+ sources and the layer chosen. Follow review-layer.md, "Comparison". Place the comparison table as a text frame under the rows, or as the comparison gallery.

Step 8: Verify, Report, Hand Off

get_screenshot of the parent section. Final message: the page and row matched, sources and tile counts, where observations landed, the section screenshot, and:

Next step: when the observations are in place, research-synthesis turns them into a problem statement, objectives, shared patterns and directions.

Cleanup: kill any local gallery server. Nothing else; the targets were not modified.

Common Mistakes