generating-code-connect

Generating Code Connect

Scope

Create Code Connect files, write figma.config.json, validate mappings, and optionally publish

Command line first

• Prefer rg, jq, and ast-grep over manual inspection
• Use CLI tools or tiny scripts to validate and inspect outputs before editing by hand
• When extracting or transforming JSON, use jq instead of ad-hoc parsing

Inputs to collect

• Repo path, default current working directory
• Figma file URL
• Framework, auto-detect or ask React vs Angular
• Component scope, comma-separated list or Enter for all
• Output directory, default codeConnect
• Permission to install @figma/code-connect locally if missing

Default behaviors

• Generate all components when the user hits Enter on scope
• Prefer local @figma/code-connect over global installs
• Do not overwrite existing Code Connect files unless the user agrees

Workflow

1. Pre-flight checks

• Parse the file key from the Figma URL
• Validate the token against the target file without printing it:
  • curl -s -o /dev/null -w "%{http_code}\n" -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" https://api.figma.com/v1/files/<fileKey>
• Check for @figma/code-connect with scripts/check_figma_cli.sh
• If the token check returns 403 but the user says it is valid:
  • Locate the token source without printing it: rg -l -g '.env*' -g 'superconnect.toml' "FIGMA_ACCESS_TOKEN|figma_access_token"
  • Ask the user to set the token in the current shell and re-run the check
  • Confirm the token is non-empty without printing it: echo ${#FIGMA_ACCESS_TOKEN}
  • Do not echo or paste the token value in any command or response

1. Detect framework

• Read package.json and look for react or @angular/core
• If ambiguous, ask the user to choose

1. Extract Figma data with figma-scan.js

• Use the bundled script for reliable extraction:

  node scripts/figma-scan.js <figmaFileUrl> \
    --token $FIGMA_ACCESS_TOKEN \
    --output codeConnect/.figma-evidence \
    --index codeConnect/.figma-evidence/figma-components-index.json
  

• The script handles all Figma API complexity including:
  • Fetching componentPropertyDefinitions via /v1/files/:key/nodes endpoint
  • Parsing variant properties from component names
  • Extracting text layers for figma.textContent()
  • Extracting slot layers for figma.children()
  • Normalizing property names to camelCase
• Do NOT use raw curl + jq for extraction - the API has edge cases the script handles
• See references/figma-extraction-spec.md for output format details