figma.enumerate-component-urls

Overview

Produces a [Name]: [URL] list for every public component set in a CDS Figma file, grouped by the file's page sections. Uses the Figma REST API directly (more reliable than the Figma MCP tools, which only expose the currently open page in the desktop app).

Requires $FIGMA_ACCESS_TOKEN to be set in the environment.

Default file: Unless the user provides a different Figma URL, always use the canonical CDS Components file:

• File key: k5CtyJccNQUGMI5bI4lJ2g
• URL: https://www.figma.com/design/k5CtyJccNQUGMI5bI4lJ2g/%E2%9C%A8-CDS-Components

Step 1 — Get all pages via the REST API

Use the file key above (or extract it from a user-provided URL — it's the segment between /design/ and the next /). Then fetch all pages at depth=1:

FILE_KEY="k5CtyJccNQUGMI5bI4lJ2g"  # override if user provided a different URL
curl -s -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/${FILE_KEY}?depth=1" | python3 -c "
import json, sys
data = json.load(sys.stdin)
pages = data['document']['children']
for p in pages:
    print(p['id'], '|', p['name'])
"

The output mixes two kinds of pages:

Collect only the component page IDs (those with the ↳ prefix) for Step 2. Ignore section header pages, cover pages, staging pages, and deprecated sections (usually marked ⛔️ Deprecated).

Step 2 — Batch-query pages for component sets

Query the /nodes endpoint at depth=2 to discover COMPONENT_SET children within each page. Batch many page IDs into one request to stay efficient:

# IDs are colon-separated (e.g. 60:512), URL-encode : → %3A and , → %2C
IDS="60%3A512%2C0%3A1%2C52733%3A3517"
curl -s -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/${FILE_KEY}/nodes?ids=${IDS}&depth=2" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for nid, node in sorted(data['nodes'].items()):
    if node is None:
        continue
    page = node['document']
    sets = [c for c in page.get('children', []) if c['type'] == 'COMPONENT_SET']
    print(f'=== {page[\"name\"]} (id: {nid}) ===')
    for s in sets:
        print(f'  [SET] {s[\"id\"]} | {s[\"name\"]}')
    if not sets:
        # No sets at top level — print child types to diagnose
        for c in page.get('children', [])[:5]:
            print(f'  [{c[\"type\"]}] {c[\"id\"]} | {c[\"name\"]}')
"

Edge case: pages that use SECTION containers

Some pages nest their component sets inside Figma SECTION nodes rather than placing them directly as page children. When depth=2 returns only SECTION entries and no COMPONENT_SET entries, re-query those section IDs at depth=2 to find the component sets inside them.

The CDS Tray page is a known example — its Tray component set lives inside a section called "Tray component".

Step 3 — Exclude internal helper sets

Component sets whose names start with . are private design helpers used internally by other components. They are not public consumer APIs and should be excluded from the output.

Known examples in the CDS file:

• Carousel: .count, .carouselPagination
• Select: .Input Chip, .Dropdown Menu, .Checkbox, .Tray/Multi Select, .Desktop Input Chips, .CheckboxGroup
• Modal: .Header
• SegmentedTabs: .tabs
• TabbedChips: .Tab Chip
• BottomTabBar: .Tab Bar Icon
• Tray: .ListCells-Mobile, .ListCells-Desktop, .TabbedChipps-Mobile, .TabbedChipps-Desktop, .Drag handle

The rule is simple: if name.startswith('.'), skip it.

Step 4 — Format the output URLs

Figma node IDs use : internally (60:512) but URLs use - (node-id=60-512).

Always link to the component node — never the page node.

Every entry must point to the actual component, whether it's a COMPONENT_SET (has variants) or a bare COMPONENT (no variants). Both are valid link targets. The only thing that's wrong is using a CANVAS (page) node ID — that lands on the whole page rather than the component.

If you're unsure of a node's type, check via the REST API — type will be COMPONENT_SET, COMPONENT, or CANVAS. Skip CANVAS IDs.

URL template:

https://www.figma.com/design/k5CtyJccNQUGMI5bI4lJ2g/✨-CDS-Components?node-id={component-set-id-with-dashes}

Output format

Group entries under the section headers from the file (Layout, Actions, Inputs, etc.) using markdown ## headings. Within each section, list components in the order they appear in the file:

## ⚡️ Actions

**Button**: https://www.figma.com/design/k5CtyJccNQUGMI5bI4lJ2g/✨-CDS-Components?node-id=0-1
**ButtonGroup**: https://www.figma.com/design/k5CtyJccNQUGMI5bI4lJ2g/✨-CDS-Components?node-id=52733-3517
**IconButton**: https://www.figma.com/design/k5CtyJccNQUGMI5bI4lJ2g/✨-CDS-Components?node-id=57214-1766

For multi-set pages, each set gets its own line. If a set name contains emoji decorators (like 🔮 Card carousel), keep them — they convey meaning (e.g., 🔮 = experimental in CDS).

Tips

• Batch aggressively: The /nodes endpoint accepts many IDs at once. Prefer fewer large requests over many small ones to stay within rate limits.
• Check for WIP pages: Pages prefixed with 🚧 are works in progress. Include them but note the WIP status in the output.
• Section order matters: Preserve the top-to-bottom page order from Step 1 when grouping under section headers — it matches the Figma file's navigation structure, which is what consumers expect.