Figma From Code Discovery Components

Skill: Component Discovery

Discovers the complete component architecture of a web application by combining two methods: (1) browser crawling to find runtime components with routes and selectors, and (2) static code scanning to find all components including those not rendered during the crawl (modals, inline-edit variants, conditional renders, etc.). Produces a merged, topologically-sorted build order (leaves first, layouts last). Also inspects the target Figma file to report existing pages, variable collections, and components.

When to Use

• Before running figma-from-code on a fresh Figma file
• When the component hierarchy may have changed and you need an updated build order
• Standalone audit of what components a site uses and how they nest
• When resuming a build and component-map.json is missing

Prerequisites

• Dev server running at {devServerUrl} (or custom URL)
• Playwright installed (node_modules/playwright-core)

Placeholders like {devServerUrl} resolve from state.json → config.

Required Inputs

• fileKey: The Figma file key (for the Figma inspection step)
• devServerUrl (optional, default http://localhost:5173): The running dev server URL

Output Files

Written to .temp/figma-from-code/:

Workflow

1. Ensure output directory exists

mkdir -p .temp/figma-from-code/

2. Verify dev server is running

curl -s --max-time 3 {devServerUrl} > /dev/null || echo "Dev server not running"

If not running, halt and tell the user to start the dev server.

3a. Enumerate routes statically

The link-following crawler only finds routes reachable via <a href>. Routes reached programmatically (e.g. navigate('/cases/new')) are invisible to it, so enumerate routes from the source code first:

1. Read the app's router configuration (e.g. <Route path=...> in React Router, file-based route folders) and list every declared path.
2. Grep the source for programmatic navigation literals: navigate(, router.push(, history.push(, and to=/href= string literals.
3. Watch for conditional renders behind a parameter value: a route like /cases/:id where the page renders a different component when id === 'new' means /cases/new is a distinct concrete route — include it explicitly.

Produce a comma-separated route list of concrete, parameterless paths (e.g. /,/cases/,/cases/new,/tasks/new). Leave :id-style dynamic routes to the crawler — it instantiates them from real links.

3b. Run the passive component discovery script

node {skillRoot}/scripts/map-components.js \
  "{devServerUrl}" --routes {enumerated_routes} --crawl --max-crawl 30 \
  --markdown .temp/figma-from-code/component-map.md \
  --output .temp/figma-from-code/component-map.json

This produces the authoritative build order — a topologically-sorted list of tiers where leaves come first and layouts come last. All subsequent phases of figma-from-code use this output. Each component found at runtime gets a capture object recording the exact URL and CSS selector (plus ordered fallbackSelectors) where it was observed.

3c. Author interaction scenarios for gated components

After the passive pass, read component-map.json and list components with capture: null / instances: 0. Many of these only mount after a user interaction (dialogs, dropdown menus, tooltips, click-to-edit inputs). For each, read its source file and call sites to find the trigger element, then write a scenario to .temp/figma-from-code/interactions.json:

{
  "scenarios": [
    {
      "id": "case-more-options",
      "route": "/cases/:id",
      "steps": [{ "click": "button[aria-label=\"More options\"]" }],
      "expect": ["MoreOptionsMenu"]
    },
    {
      "id": "editable-title-edit",
      "route": "/cases/:id",
      "steps": [{ "click": "main h1" }],
      "expect": ["EditableTitle", "EditControls"]
    }
  ]
}

• route may be a visited concrete route or a :param pattern — patterns resolve against a concretely visited URL.
• steps run in order; verbs are click, hover, press (e.g. "Escape"), and fill ({"fill": {"selector": "...", "value": "..."}}). Each step accepts an optional settle (ms, default 400).
• expect lists component names the scenario should reveal — used to report scenarios that need refinement.
• Prefer click/hover steps: only those are replayed at screenshot time (Phase 2.5). press/fill steps run during discovery but are not part of the capture replay.

Safety rules (mandatory — copy into every scenario review):

• Never click elements whose text or handler indicates destruction or persistence: Delete/Remove/Confirm inside an already-open confirmation dialog, Save, Submit, or any type="submit" button. Opening a confirmation dialog is allowed; confirming it is not.
• Prefer aria-label or role+text based step selectors; never positional (nth-of-type) ones.
• Each scenario must be independently replayable from a fresh page load — never depend on state left by a previous scenario.

3d. Run the interaction pass

node {skillRoot}/scripts/map-components.js \
  "{devServerUrl}" \
  --augment .temp/figma-from-code/component-map.json \
  --interactions .temp/figma-from-code/interactions.json \
  --markdown .temp/figma-from-code/component-map.md \
  --output .temp/figma-from-code/component-map.json

--augment seeds from the existing map and skips the passive crawl, so this pass only runs the scenarios. Read interactionResults from the output:

• status: "ok" — scenario ran; found lists revealed components (now carrying capture with the replay recipe).
• status: "missing_expected" — scenario ran but some expected components were not revealed; missing lists them.
• status: "failed" / "no_matching_route" — step selector or route problem; error has details.

For scenarios that did not reveal their expected components, refine the step selectors and re-run 3d (max 2 refinement iterations). Debug a single scenario interactively with:

node {skillRoot}/scripts/discover-components.js "{devServerUrl}{route}" --click "{trigger}" --list

Components still without capture after refinement are genuinely non-renderable from the live app (loading/error states, hover-only primitives) — record each with its reason for the final report.

4. Normalize component names

The DOM scanner extracts React component names from the fiber tree, which may differ from the Figma naming convention for icons and assets:

• Lucide icons: scanner reads the internal displayName (e.g. EllipsisVertical) rather than the import alias used in code (e.g. MoreVertical)
• SVG asset wrappers: scanner sees the wrapper component name (e.g. CartonLogo) rather than the Figma asset name (e.g. Asset/CartonLogoSvg)

Run the normalization script to align names with Figma conventions. This requires icons.json from Phase 0b.

node {skillRoot}/scripts/normalize-component-map.js \
  .temp/figma-from-code/component-map.json \
  .temp/figma-from-code/icons.json \
  --write

If icons.json does not yet exist (Phase 0b hasn't run), skip this step — the orchestrator will re-run normalization after Phase 0b completes.

The script resolves names via three strategies:

1. Direct icon match: component name is a known icon import name → prefix with Icon/
2. Lucide alias resolution: component name is a Lucide canonical name that differs from the import alias → resolve via lucide-react exports → prefix with Icon/
3. Asset prefix match: component name is a prefix of a known asset name → prefix with Asset/

5. Discover frontend source directories

Run the code scanner in discovery mode to locate component directories:

node {skillRoot}/scripts/discover-code-components.js \
  --discover --root .

Read the JSON output and automatically apply the following default exclusions (do not wait for user input — this is a subagent):

• Any directory named ui/ that is a direct child of a components/ folder (shadcn primitives, not application components)
• Any directory path containing __tests__, __stories__, .storybook, or node_modules
• Any directory path containing /dist/ or /build/

For each excluded directory, record the directory path and the exclusion reason. Include the final componentDirectories list and the list of any excluded directories with their reasons in the discovery summary returned to the orchestrator. The orchestrator will surface these to the user at the next user-facing checkpoint so they can request adjustments if needed.

After running --discover and applying exclusions, write both componentDirectories and excludedDirectories into component-map.json as top-level fields so they are preserved through the --scan merge in Step 6 and available to the summary script in Step 10:

// Merge into component-map.json after --scan completes
const map = JSON.parse(fs.readFileSync('.temp/figma-from-code/component-map.json', 'utf-8'));
map.componentDirectories = componentDirectories; // [{ path, componentCount, subdirs }]
map.excludedDirectories = excludedDirectories;   // [{ path, reason }]
fs.writeFileSync('.temp/figma-from-code/component-map.json', JSON.stringify(map, null, 2));

6. Scan code for all components

Run the code scanner in scan mode with the confirmed directories:

node {skillRoot}/scripts/discover-code-components.js \
  --scan {confirmed_dir_1} {confirmed_dir_2} \
  --browser-map .temp/figma-from-code/component-map.json \
  --output .temp/figma-from-code/component-map.json \
  [--exclude {excluded_dirs}]

This merges code-discovered components into the browser-discovered map. Each component gains a source field ("browser", "code", or "both") and a codeDependencies array. Tiers are recomputed from static import analysis to include all components. Browser data (routes, selector, instances) is preserved for components found by both methods.