bug: `/understand-figma`: top-level Figma `GROUP` nodes are silently dropped, losing all nested screens

[cbolden15]

What happened?

packages/core/src/figma/parse/parse-document.ts's handlePageChild() function only handles FRAME, COMPONENT, COMPONENT_SET, and SECTION (which flattens/recurses) as direct children of a Figma page (CANVAS). A top-level GROUP node falls into the default: break case and is silently ignored — none of its descendants (including nested FRAMEs, which are the actual "screens" the parser is trying to extract) are visited or added to the graph.

This is a real-world, not edge-case, scenario: many designers organize their screens inside a GROUP on the canvas (e.g. for freeform layout/versioning — "Designs", "New_Designs" style groups) rather than leaving every screen as a bare top-level FRAME. Any file structured this way loses the vast majority of its content silently — no error, no warning, just an artificially tiny graph.

Expected: All FRAMEs nested inside GROUPs (at any depth) should be discovered and emitted as screen nodes, the same as top-level FRAMEs, with a contains edge from the page.

Actual: FRAMEs nested inside a GROUP are never visited.

Proposed fix:

In packages/core/src/figma/parse/parse-document.ts, in the handlePageChild() switch statement, add a case "GROUP": alongside the existing case "SECTION": so both flatten/recurse identically:

    case "SECTION":
    case "GROUP": {
      // GROUP behaves like SECTION here: it has no useful semantics of its
      // own for the design graph, but its children (frequently the actual
      // screens) must still be visited.
      for (const sub of child.children ?? []) handlePageChild(sub, pageId);
      break;
    }

This is a minimal, low-risk change (one added case label, same recursion the code already uses for SECTION) and was verified against a real-world file (see reproduction below): 1 → 35 screens found, all correctly named and thumbnailed. Happy to open a PR with this change plus a regression test (a fixture Figma document with a GROUP wrapping a FRAME, asserting the FRAME is still discovered as a screen) if a maintainer confirms this is the right direction — per CONTRIBUTING.md, filing this issue first before any PR.

Minimal reproduction

1. In Figma, create a page with a top-level GROUP node containing one or more FRAMEs.
2. Run /understand-figma <file-url> against that file.
3. Observe the scan summary and resulting knowledge-graph.json.

Verified against a real test file (Figma design "joehamilton003", file key hzZjDc3mb5XrZXxqDDpiSk). The page had 4 top-level children: 3 GROUPs ("Designs" x2, "New_Designs") and 1 loose FRAME (a 24x24 icon). The stock scanner reported:

Figma scan: 1 pages, 1 screens, 0 components, 0 sets, 0 instances, 0 tokens

— i.e. only the loose icon frame was found. The three GROUPs actually contained 35 real app screens between them (an onboarding/BLE-pairing flow, a BAC-level result display with several iterations, and a "New_Designs" set with Menu / Log My Drinks / Calendar / Bar Chart / empty-state popups). After patching the parser to treat GROUP like SECTION, the scan correctly reported:

Figma scan (fixed): 1 pages, 35 screens, 0 components, 0 sets, 0 instances, 0 tokens

Plugin version

2.9.4

Platform / client

Claude Code (CLI)

OS + Node version

macOS (darwin), Node v22.21.0

Primary language of the analyzed project

N/A (Figma design file, not a codebase)

Approximate file count of the analyzed project

N/A — single Figma file, 1 page, 4 top-level nodes (3 GROUPs + 1 FRAME)

Relevant logs

Figma scan: 1 pages, 1 screens, 0 components, 0 sets, 0 instances, 0 tokens