--- name: 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](https://studio-documentation.contentstackapps.com/figma-plugin/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`](authenticate-cma.md): `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= 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](https://studio-documentation.contentstackapps.com/figma-plugin), [Prepare your Figma file](https://studio-documentation.contentstackapps.com/figma-plugin/prepare-your-figma-file), [Generate a React component from a Figma design](https://studio-documentation.contentstackapps.com/figma-plugin/generate-react-components-from-figma). 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=` | 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=` | 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=` or `--component-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=` | 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: ```bash csdx --version csdx studio:project:get ``` If `csdx` isn't installed: ```bash 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: ```bash csdx studio:project:set --project-id= ``` 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: ```bash csdx studio:component:sync --component-path= ``` 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=` 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 ```bash csdx studio:component:add --component-id= ``` `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](https://studio-documentation.contentstackapps.com/studio-cli/generate-from-a-design)). ### Step 5: (Optional) Run `Design token: add` if tokens were generated If `designTokenId` was provided: ```bash csdx studio:design-token:add --design-token-id= ``` 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](https://studio-documentation.contentstackapps.com/design/register-design-tokens#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`): ```ts import "./studio/register-design-tokens"; ``` Verify the import comes BEFORE any `` 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](https://studio-documentation.contentstackapps.com/studio-cli/push-your-code-into-studio#where-registrations-get-written)). - **Absent:** no entry. Install the SDK and run `Add` again, or register by hand (`register-component` skill). To register a component `Add` didn't: ```bash csdx studio:component:register --component-path= ``` ### Step 7: Print next steps ``` Generated from Figma. Source: Tokens: (if design tokens were run) Registered: 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=` 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](register-component.md). - [ ] If Sync was needed: `csdx studio:component:sync` ran successfully (CLI exits 0) - [ ] `csdx studio:component:add --component-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=` 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 `` | | 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](https://studio-documentation.contentstackapps.com/figma-plugin/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