Import and Manage New Designs

Note: Studio is currently part of an Early Access Program and may not be available to all users. Contact the Contentstack support team; they will coordinate with the appropriate stakeholders to review eligibility.

Importing and managing new designs in Studio enables designers and developers to convert Figma layouts into Studio-compatible components.

This process enables designers and developers to convert Figma designs into Studio-compatible JSON that can be pasted directly into the Studio canvas or used to generate UI code within their project codebase.

This guide demonstrates two methods for bringing new designs into Studio:

• Importing designs using the Studio Figma Plugin.
• Generating and registering code components using the Studio CLI.

Before you begin, ensure you have the following:

• Access to Studio.
• Node.js is installed on your local machine.
• Studio Figma Plugin is installed in your Figma account.
• Contentstack CLI package and the Studio CLI plugin are installed.
• (Optional) Studio React SDK setup in your project if you plan to generate JavaScript components.
• Admin or Developer permissions to modify the composition structure.

The Studio Figma Plugin converts Figma designs into Studio-compatible JSON, which can be pasted directly into the Studio Canvas. The plugin only converts the design visuals. To generate functional logic, refer to the “Generate UI Code Using the Studio CLI” section.

To integrate Figma designs with Studio, open your Figma file and perform the following steps:

1. From the Figma menu, click Actions, search for Contentstack Studio, and select it.
2. A login modal appears where you can:
   1. Select the region.
   2. Authorize the connection.
   3. Authenticate in the browser when redirected.
   4. Select the organization to complete authorization.
3. After authorization, return to Figma. The plugin displays the list of projects linked to your organization in Studio. Select the Studio project and click Proceed.
4. Select a frame or component, or hold Shift and click to select multiple items. Alternatively, drag a selection box across the canvas to select multiple frames.

   Tip: If you use a custom design system, map your pre-built components and design tokens in Figma before generation. This avoids duplicate components and ensures consistency across the design system.

5. Click Generate Design. The plugin converts the selected design into Studio-compatible JSON.
6. After generation, two options appear:
   1. Copy to Studio

      Copies the generated component as Composition JSON to the clipboard for use in the Studio Canvas.

      Use this when:

      • The design is final and can be used as-is.
      • You want to visualize or prototype layouts directly inside Studio.
      • No custom logic or code-level modifications are required.
   2. Copy CLI Command

      Generates a CLI command that will import the design into the local project and register it automatically with Studio.

      Use this when:

      • The design must be generated as code.
      • The component will become part of the project’s design system.
      • The component requires logic, customization, or future maintenance in the codebase.
7. Click Copy to Studio to copy the JSON.
8. Open the Studio Canvas and paste the copied design. The design appears immediately in Studio as a usable component.

The Figma Plugin simplifies importing visual layouts and is ideal for non-developers and content creators who want to build or update UI quickly.

The Studio CLI is designed for developers who want to generate JavaScript or TypeScript components with customizable behavior. This method imports the design into the project and registers it automatically in Studio.

To integrate Figma designs using Studio CLI, open your Figma file and perform the following steps:

1. In the Figma Plugin, copy the CLI command displayed under Copy CLI Command.
2. Ensure the local project is already configured with the Studio CLI and matches the selected Studio project.
3. Open the terminal and run the copied command:
   csdx studio:component:add --component-id=<component-id>

4. A prompt appears: Describe your component.
   • Enter a description to modify the generated design (for example, “Add a button below the image,” or “Change the background color”).
   • Leave the input blank to generate the default component.
5. The CLI analyzes the project automatically:
   • Detects the framework and language (for example, React and TypeScript).
   • Generates UI component code accordingly.
6. The CLI creates:
   • A component file (for example, FinancialImageLayout.tsx).
   • A registerComponents file to register the component in Studio.

     Note: The number of generated files varies depending on the size and complexity of the design.

7. If prompted with Would you like to make changes to the generated component?
   • Enter Yes to modify the generated code with an additional prompt.
   • Enter No to continue without changes.
   • 
8. When generation completes, the files appear in the project folder.

1. Return to Studio.
2. In the Components tab, expand Registered Components.
3. Locate the newly created component (for example, “Financial Image Layout”).
4. Drag and drop the component onto the Studio Canvas to view the generated UI.

The Studio CLI handles component registration automatically, so no manual import or registration steps are required.

Mapping helps the Figma Plugin reuse existing components registered to Studio when exporting new designs. This avoids duplicate components and ensures consistency across the design system.

To map components to the Figma plugin:

1. Go to the Component Mapping tab to view the detected Figma components and corresponding code components.
2. Click Auto Map to match design layers to code components automatically.

   Note: The mapping is based on component name, description, and properties. Layers without a matching component remain unmapped and can be linked manually.

3. Review and adjust mappings before export to ensure accuracy.

This step ensures future design exports and code generation remain accurate and aligned with the existing component library.

Studio supports bringing design tokens from Figma into the codebase and keeping them synchronized.

The Studio Figma Plugin is ideal for designers who want to export design tokens directly from Figma.

• Designers can export color, typography, spacing, and component-level tokens.
• These tokens are automatically registered in the Studio project.
• Registered tokens become available inside the Studio Canvas for component styling.

The Studio CLI allows developers to manage design tokens directly from their codebase.
It supports two major workflows:

1. Import tokens exported from the Figma Plugin
   • Open the Design Tokens tab in the Figma plugin and copy the provided command for your design token set.
   • Run the copied command in your terminal:
     csdx studio:design-token:add --design-token-id=<design-token-id>

   • The CLI generates and registers design token files directly to your project.

2. Auto-generating design tokens from existing project files

   The CLI can analyze your project files (JS/TS, CSS, global.css) to automatically extract design tokens and generate a token definition file that can be registered in Studio.

   Additional Resource: To learn more about importing design tokens from project files refer to the Import Design Tokens from Project Files Using Studio CLI document.

• Use the Studio plugin in Figma to generate code for selected components.
• Copy the generated components and paste them into the Studio editing canvas, or use the command to modify component functionality and register them through the CLI.
• Once registered, drag and drop the components from the Registered Components tab in Studio.