{"id":34409623,"url":"https://github.com/bitovi/superconnect","last_synced_at":"2026-01-20T19:12:08.705Z","repository":{"id":329024004,"uuid":"1110213890","full_name":"bitovi/superconnect","owner":"bitovi","description":"AI-powered code generation tool that writes your Figma Code Connect mappings for you","archived":false,"fork":false,"pushed_at":"2026-01-13T19:53:27.000Z","size":1013,"stargazers_count":21,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T21:08:57.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitovi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-04T21:48:56.000Z","updated_at":"2026-01-13T19:53:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitovi/superconnect","commit_stats":null,"previous_names":["bitovi/superconnect"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/bitovi/superconnect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitovi%2Fsuperconnect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitovi%2Fsuperconnect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitovi%2Fsuperconnect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitovi%2Fsuperconnect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitovi","download_url":"https://codeload.github.com/bitovi/superconnect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitovi%2Fsuperconnect/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28609887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T18:56:40.769Z","status":"ssl_error","status_checked_at":"2026-01-20T18:54:26.653Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-20T14:00:51.174Z","updated_at":"2026-01-20T19:12:08.689Z","avatar_url":"https://github.com/bitovi.png","language":"JavaScript","readme":"# Superconnect: Code Generator for Figma Code Connect\n\nSuperconnect is an AI-powered code generation tool that writes your Figma Code Connect mappings for you. It does this by:\n\n- Scanning your Figma file via API\n- Exploring your React or Angular component repo\n- Using coding agents to generate `.figma.tsx` or `.figma.ts` files\n\nThen you publish these back to your Figma file using Figma's own CLI tool to `figma connect publish`.\n\nFigma Code Connect [also offers an interactive setup to help create Code Connect files](https://developers.figma.com/docs/code-connect/quickstart-guide/#use-the-interactive-setup), but Superconnect:\n\n- **Works fully automatically** - no interactive terminal prompts, maps all components in one run\n- **Supports Angular/HTML** - Figma's interactive setup and AI features only work for React components; Angular requires manual mapping\n- **Lets you bring your own AI model** - use Claude, OpenAI, or switch to a smarter model if needed\n\n# Installation\n\n- Run directly with npx (recommended for one-off use)\n  - `npx @bitovi/superconnect@latest`\n\n- Install globally from npm\n  - `pnpm add -g @bitovi/superconnect`\n  - `npm install -g @bitovi/superconnect`\n  - `yarn global add @bitovi/superconnect`\n\n# Required environment and config\n\n- Requires Node.js \u003e= 22.0.0\n- Environment variables (set in your shell or in a `.env` file in your repo)\n  - `FIGMA_ACCESS_TOKEN` – Figma personal access token (see [Figma access token](#1-figma-access-token) below)\n  - One AI provider key (depending on which API you choose):\n    - `ANTHROPIC_API_KEY` – for Anthropic Claude (the default)\n    - `OPENAI_API_KEY` – for OpenAI or OpenAI-compatible endpoints\n\n- superconnect.toml\n  - Superconnect looks for this config file in the current working directory\n  - Create it with `superconnect init`\n  - If missing, `superconnect` will ask you to run `superconnect init`\n\n# Workflow\n\n## 0. Pre-requisites\n\nYou have:\n\n- a Figma file with components, an Enterprise Figma account, and write permissions to that file\n- a repo implementing those same components (React or Angular)\n- the Figma Code Connect CLI installed (`@figma/code-connect`)\n  - `npm install -g @figma/code-connect`\n  - `pnpm add -g @figma/code-connect`\n  - `yarn global add @figma/code-connect`\n\n## 1. Figma access token\n\nSuperconnect relies on a Figma personal access token, which you create through Figma. To get the token:\n\n- In Figma, open your account menu\n- Choose **Settings** (or **Profile \u0026 Settings**)\n- Scroll to **Personal access tokens**\n- Click **Generate new token** and make sure it has the scopes listed below\n- Give it a descriptive name and copy the token value\n- In your terminal environment (or `.env` in your component repo), set\n  - `FIGMA_ACCESS_TOKEN=\u003cyour token here\u003e`\n\n### Scopes for the token\n\n- Files\n  - `file_content:read` (to read components)\n- Development\n  - `file_code_connect:write`  (to write Code Connect content)\n  - `file_dev_resources:read` + `write`  (to read and write Code Connect content)\n\n## 2. Publish Figma assets (if not already published)\n\nFor Code Connect mappings to work, assets from the design system must first be \"published\" within Figma. If you've already published your design system components, you can skip this step.\n\nTo publish (or verify publication status):\n\n- Switch to the **Assets** tab in the left sidebar (not in dev mode)\n- Click the **Library** icon (looks like a book) to open the **Manage libraries** dialog\n- Under **This file**, you should see your design system file listed\n- If not already published, click **Publish…**\n\n(Reminder: your Figma design system file should be in an Enterprise org where you have edit rights.)\n\n## 3. Code Generation\n\nFrom the root of your React or Angular component repo:\n\n- Run `superconnect init` to create `superconnect.toml`\n- Run `superconnect` to generate Code Connect files\n  - For CI/non-interactive runs, use `superconnect --yes`\n\n`superconnect` will proceed to:\n\n- Inspect the repo and figure out if it's React or Angular (combination projects not supported!)\n- Scan the components in your Figma file\n- Find the corresponding components in your repo\n- Write out a set of Code Connect mappings to:\n  - `codeConnect/*.figma.tsx` for React\n  - `codeConnect/*.figma.ts` for Angular\n- Generate `figma.config.json` at the repo root so the Figma CLI knows what to publish\n\nAt this point you have local Code Connect mappings but Figma does not see them yet.\n\n## 4. Publish mappings to Figma \n\nNext you push the generated mappings back to Figma, using Figma's own CLI. You must have `@figma/code-connect` installed in the component repo or globally. Run:\n\n```bash\nfigma connect publish\n\n# or, without a global install\nnpx --package @figma/code-connect figma connect publish\n```\n\nThis command reads `figma.config.json`, uploads your Code Connect files, and associates them with the Figma file.\n\n## 5. Profit\n\nNow you can inspect the mappings in Figma.\n\n- Open the design system file and switch into Dev Mode\n- Select an instance of a component you mapped (for example, a Button)\n- In the right-hand sidebar, scroll to the **Code Connect** section\n- Click the **Connect Components** button or the **View connections** button and then select the Button component\n\nYou should now see:\n\n- The Code Connect mapping written by Superconnect\n- The generated example snippet for your framework (React JSX or Angular template)\n- Any props that were inferred from Figma variants or component properties\n\nIf the **Code Connect** section is missing\n\n- Double-check that\n  - `figma connect publish` completed successfully\n  - The Assets panel shows your design system file as published\n  - Your Figma user has access to the Enterprise org and file where mappings were published\n\n\n# How It Works\n\nSuperconnect runs a five-stage pipeline:\n\n1. **Package scanner** - Scans your component package for React or Angular components and structure\n2. **Figma scan** - Downloads component metadata from your Figma file via API\n3. **Orienter** - AI decides which source files correspond to each Figma component\n4. **Codegen** - AI generates `.figma.tsx` (React) or `.figma.ts` (Angular) mappings\n5. **Finalizer** - Writes `figma.config.json` and prints a summary\n\nAll artifacts are written to `superconnect-logs/` and `codeConnect/` directories in your repo. For implementation details, see `docs/ARCHITECTURE.md`.\n\n\n# Agent Configuration\n\nSuperconnect uses Claude's Agent SDK by default, which allows the model to intelligently explore your codebase using tools. This typically results in lower token usage and better context selection.\n\nConfigure the `[agent]` section in `superconnect.toml`:\n\n```toml\n[agent]\n# Backend for code generation:\n#   \"anthropic-agent-sdk\"     (default) — Claude explores your codebase using tools\n#   \"anthropic-messages-api\"  — Anthropic Messages API (curated context)\n#   \"openai-chat-api\"        — OpenAI Chat Completions API or compatible provider\napi = \"anthropic-agent-sdk\"\nmodel = \"claude-sonnet-4-5\"\n```\n\n| API | Environment Variable | Description |\n|-----|---------------------|-------------|\n| `anthropic-agent-sdk` (default) | `ANTHROPIC_API_KEY` | Claude Agent SDK with tool-based exploration |\n| `anthropic-messages-api` | `ANTHROPIC_API_KEY` | Anthropic Messages API (deterministic context) |\n| `openai-chat-api` | `OPENAI_API_KEY` | OpenAI Chat Completions API or compatible endpoint |\n\n**When to use `anthropic-messages-api` (Messages API):**\n- Provider flexibility — works with OpenAI, local models, or other LLM providers\n- Deterministic context — you control exactly what the model sees\n- Restricted AI access — model cannot explore beyond curated files\n\n**Using OpenAI-compatible endpoints:** Set `api = \"openai-chat-api\"` and add `llm_proxy_url` for services like LiteLLM, Azure OpenAI, vLLM, or LocalAI.\n\n# Output Files\n\nGenerated files in your repo:\n\n**superconnect-logs/** - Pipeline artifacts\n- `package-scan.json` - Detected components, framework info, and package metadata\n- `figma-components-index.json` - Figma component catalog\n- `figma-components/*.json` - Per-component Figma metadata\n- `orientation.jsonl` - File-to-component mappings\n- `orienter-agent.log`, `codegen-summaries/*.json`, `codegen-agent-transcripts/*.log` - Agent logs\n\n**Code Connect files** - By default, placed next to source components\n- `src/components/Button/Button.figma.tsx` next to `Button.tsx` (React)\n- `src/app/button/button.component.figma.ts` next to `button.component.ts` (Angular)\n- Set `colocation = false` in config to use centralized `codeConnect/` directory instead\n\n**Root** - Configuration\n- `figma.config.json` - Tells Figma CLI what to publish\n\n\n# Interrupts \u0026 Reruns\n\nThe pipeline is designed for graceful partial runs:\n\n- Ctrl+C during codegen\n    - Codegen finishes the current component, then stops processing more\n    - superconnect-logs/codegen-summaries/, codegen-agent-transcripts/, and codeConnect/ contain whatever was completed so far\n    - The pipeline still runs the finalizer, so you get an accurate summary of what was built versus skipped\n- Rerunning without `--force`\n    - Package scan, Figma scan, and orienter are skipped if their outputs already exist\n    - Codegen re-invokes the agent for each mapped component but:\n        - Does not overwrite existing .figma.tsx files unless `--force` is used\n        - Marks such components as “skipped” with an explanatory reason\n- Rerunning with `--force`\n    - Clears relevant logs and lets codegen overwrite existing .figma.tsx files\n    - Upstream stages are re-run as needed (Figma scan, summary, orientation)\n\nThis makes it safe to interrupt, inspect, tweak prompts/config, and then rerun the pipeline without losing context\n\n\n# Troubleshooting\n\n## Getting an old version with npx\n\nnpx caches packages locally. If you're getting an older version of Superconnect:\n\n```bash\n# Always use @latest to ensure you get the current version\nnpx @bitovi/superconnect@latest\n\n# Or clear the npx cache entirely\nnpx clear-npx-cache\n# Then run again\nnpx @bitovi/superconnect@latest\n```\n\n## Missing environment variables\n\nIf you see errors about missing API keys:\n\n1. **FIGMA_ACCESS_TOKEN** - See [Figma access token](#1-figma-access-token) above\n2. **ANTHROPIC_API_KEY** or **OPENAI_API_KEY** - Get from your AI provider's dashboard\n\nSet these in your shell or in a `.env` file in your component repo.\n","funding_links":[],"categories":["Development Utilities"],"sub_categories":["AI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitovi%2Fsuperconnect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitovi%2Fsuperconnect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitovi%2Fsuperconnect/lists"}