figma-generate-components

When to use

Generate React components from a Figma design and register them with Studio via the Studio Figma Plugin + csdx studio:component:sync/add/register CLI commands. Optionally imports Figma design tokens.

Use when the user wants real, committable React components in their project generated from a Figma design (component library, design system, frames). NOT for one-off pastes (for that, point them at Copy and paste from Figma to Studio, which uses the plugin's Copy to Studio: Studio can't read a frame copied in Figma itself). Phrases: "generate components from Figma", "Figma to React", "import my design system". This skill produces source files, registry entries and (optionally) design tokens.

Auth preflight: settle the credential before the first API call. Resolve it OAuth-first per authenticate-cma: CS_OAUTH_ACCESS_TOKEN, else the Contentstack MCP's stored session: Read that skill for where it is, even with no MCP connected. Never ask the user for a session authtoken. If nothing resolves, or a refresh fails with 400 invalid_refresh_token, hand them ! CONTENTSTACK_REGION=<code> npx @contentstack/mcp --auth (it needs a TTY and a browser, so it cannot be run for them) and wait. 403 error_code 316 is a valid credential aimed at another org: fix the org or the api_key, do not re-authenticate.

Generate Studio components from a Figma design

Standard: reference pages

The steps below are enough to run this. For anything else, Read the owning page, which wins where it disagrees with the skill: The Studio Figma plugin, Prepare your Figma file, Generate a React component from a Figma design.

Two sides:

Side	Tool	Who drives it
Designer	The Studio Figma plugin	Designer, in Figma
Developer	Studio CLI (csdx)	Developer, in the terminal

They meet via a Component ID (and a Design Token ID) the plugin generates and the CLI consumes. No Figma MCP server is involved in this route (decompose-design is the one that reads Figma through an MCP).

The four CLI commands

Name the command as you run it.

Command name	csdx invocation	What it does
Project	csdx studio:project:set / csdx studio:project:get	Connect the CLI to a Studio project. Every later command scopes to it. It must be the plugin's project.
Sync	csdx studio:component:sync --component-path=<path>	Send existing code components (name, props, import path) to the project so Auto Map can match Figma components to them.
Add	csdx studio:component:add --component-id=<id>	Write a React component from a Component ID, plus a register entry if @contentstack/studio-react is installed.
Register	csdx studio:component:register --component-path=<path> or --component-dir=<dir>	Write the registration for a local or custom component so authors can use it on the canvas.
(aux) Design token: add	csdx studio:design-token:add --design-token-id=<id>	Pull the plugin's imported design tokens into register-design-tokens.ts.

Task

Step 0: Detect which side of the workflow the user is on

If the user has a Component ID (from the export screen or History), jump to Step 4.

If not, walk them through Steps 1 to 3, then come back for Step 4.

Step 1: Verify CLI is installed and a project is linked

Run:

csdx --version
csdx studio:project:get

If csdx isn't installed:

npm i -g @contentstack/cli
csdx plugins:install @contentstack/studio
csdx config:set:region   # pick the user's Contentstack region
csdx login --oauth        # opens browser for OAuth

If csdx studio:project:get does NOT return the project the user wants:

csdx studio:project:set --project-id=<projectId>

Use the projectId input, else ask. It must match the plugin's project and region.

Step 2: Sync existing components (if using Auto Map)

If componentPathToSync was provided OR this is the first run on this repo, send existing components to the project so Auto Map can match against them:

csdx studio:component:sync --component-path=<componentPathToSync>

Skip if nothing changed since last sync.

Step 3: Have the designer (or the user themselves) run the Studio Figma Plugin

Print these instructions verbatim:

Designer step (in Figma):

1. Run the Studio Figma plugin (from Figma Community if needed) in a file you can edit: it adds a temporary frame while exporting a preview, then removes it. Sign in: choose your region, click Authorize, approve in the browser tab within five minutes. On Select Project, choose the project the CLI is linked to and click Proceed.
2. Select the frame(s) or component(s) (Shift+click for multiple). Over 300 elements or 6,000 pixels wide can't be generated: select smaller sections.
3. Component Mapping tab: click Auto Map. An AI model pairs Figma components with synced code components by component names and prop names and types. Rows show a count such as 1/1, or empty. Click a row to map by hand, then Save. A mapped component arrives as yours, an unmapped one is rebuilt.
4. Optional, Design Tokens tab: click Import Design Tokens and note the Design Token ID in the command it shows.
5. Design tab: add a note if needed (Add note for this layer (optional), e.g. "Make this a carousel"). With several layers, Showing: 1/N pages through them and Add a shared note for all layers covers all. Pick Optimize for responsiveness (default) or Fixed-size screens: one choice covers every layer.
6. Click Generate Design.
7. On "Your Export is Ready!", copy the csdx studio:component:add --component-id=<id> under Incorporate this code into your application. Copy to Studio copies composition JSON instead. Regenerate calls the AI model again.

Then ask: "Paste the Component ID (or the full CLI command) the plugin gave you."

If they paste a full command like csdx studio:component:add --component-id=abc123, extract abc123.

For an earlier design, History in the plugin footer has Copy CLI command per row. It's shared with the project team. Load more shows older rows.

Step 4: Run Add to materialise the Figma design as React source

csdx studio:component:add --component-id=<componentId>

Add takes one flag. The rest is interactive, so run it where the user can answer. It matches the project's styling method and writes:

• A React .tsx component file (note its path) and its style file
• A register entry, only if @contentstack/studio-react is in package.json (otherwise silently none)

The CLI asks "Describe your component (optional):". The user can describe it, or press Enter. Examples:

• "Use the existing useBreakpoint hook for the responsive switch"
• "Use clsx for conditional class names"
• "Match the export style of src/components/Button.tsx"

It then asks "Make changes to the generated component?" and "Create a Section with ?" (see Generate from a design).

Step 5: (Optional) Run Design token: add if tokens were generated

If designTokenId was provided:

csdx studio:design-token:add --design-token-id=<designTokenId>

The CLI fetches the saved tokens. When no register-design-tokens.ts exists yet, it asks two questions:

1. Use Studio's default design tokens? No default: type y or n.
2. Allowed values level: dynamic (preselected), tokens or arbitrary. Choose tokens if authors should pick from the tokens. See Choose how strict the Design tab is.

It writes the tokens and register-design-tokens.ts into a studio folder. Then add the import to the app entry (e.g. src/main.tsx or src/bootstrapStudioSdk.ts):

import "./studio/register-design-tokens";

Verify the import comes BEFORE any <StudioComponent /> mount.

Step 6: Confirm the component is registered

Check package.json for @contentstack/studio-react:

• Present: Add wrote the entry. Confirm the app imports that file (where registrations go).
• Absent: no entry. Install the SDK and run Add again, or register by hand (register-component skill).

To register a component Add didn't:

csdx studio:component:register --component-path=<path-from-step-4>

Step 7: Print next steps

Generated <ComponentName> from Figma.

Source:     <component-path-from-add>
Tokens:     <register-design-tokens.ts>   (if design tokens were run)
Registered: <register entry written by Add, or by hand if the SDK was absent>

In Studio, open any composition and look for the new tile in the Components tab.
Drop it on a canvas to verify the render matches the Figma source.

Re-run `csdx studio:component:sync --component-path=<path>` so this component
(or any other code change) is visible to the next plugin run's Auto Map.

Inputs needed from the user

1. componentId: required for Steps 4 to 7. If absent, walk through Steps 0 to 3 first.
2. designTokenId: optional, only if the plugin imported tokens.
3. projectId: optional, only if the project isn't already linked.
4. componentPathToSync: optional, only if code components changed since last sync OR first run.

Ask when:

• csdx isn't installed AND the user hasn't confirmed they want to install it
• Multiple Studio projects could be the target. Confirm with csdx studio:project:get first
• The user isn't sure they can edit the Figma file

Acceptance

The skill succeeds only when ALL are true:

• csdx studio:project:get returns the intended project
• Every generated component carries its CSLP tags: studioAttributes spread on the root element and wrap: false in its register entry, and each bindable prop's $-twin spread on the element rendering it. Confirmed in the DOM: the root and each bound text/image element show data-cslp. Without it the component renders but Visual Editor and Live Preview cannot edit it. See register-component § The studioAttributes contract.
• If Sync was needed: csdx studio:component:sync ran successfully (CLI exits 0)
• csdx studio:component:add --component-id=<id> produced a .tsx and a style file at known paths
• If tokens were involved: register-design-tokens.ts exists AND is imported from the app entry point
• The component is registered: Add wrote a register entry, or Register or a hand-written entry did
• After dev server restart, the new component appears in Studio's palette with the correct name + thumbnail
• Dropping the new component on a canvas renders without console errors

If any check fails, surface the specific failure with file paths.

Common pitfalls

Pitfall	Why it bites	Fix
Skipping Sync before the designer runs the plugin	Auto Map has nothing to match, so every Figma component is rebuilt as plain Studio components	Run csdx studio:component:sync --component-path=<path> before Step 3
Running Add with an older Component ID	Every run has its own ID, so you get the older design. A wrong project or region reports "not found"	Copy the ID from the latest export screen or History, and match the plugin's project and region
Add finishes but the component never reaches the canvas	@contentstack/studio-react isn't in package.json, so no register entry was written, silently	Install the SDK and run Add again, or register by hand
Not importing register-design-tokens.ts from the app entry	Tokens never register. They exist in the file but Studio doesn't see them	Import it in main.tsx (or wherever the SDK bootstraps) before any <StudioComponent />
Running Register on a path the CLI doesn't recognize as a component	It needs a component file (named export matching a React component) or a directory of them	Pass the exact .tsx path Add wrote, or the parent directory
Confusing Sync and Register	They look similar but face different audiences	Sync is for the Figma plugin (Auto Map). Register is for authors on the Studio canvas.
Mixing responsive + fixed-size in one plugin run	One responsiveness choice covers every layer	Run the plugin twice, once per mode
Read-only Figma file	The plugin needs edit access for its temporary preview frame	Get edit access, or duplicate the file into one you own

See also

• Copy and paste from Figma to Studio: the simpler "Copy to Studio" flow, for a one-off composition tree instead of committable React source
• register-component skill: for hand-authored components (skips the plugin entirely, only runs Register)
• import-design-tokens skill: for token imports from non-Figma sources